最近、 SpringMvcと swagger-ui(v2)を使用して RESTful API を作成しました。Postman の Import 機能に気づきました。
私の質問は、Postman に必要なファイルをどのように作成するかということです。
私はSwaggerをよく知りません。
ベストアンサー1
私は PHP で作業しており、API をドキュメント化するために Swagger 2.0 を使用しています。Swagger ドキュメントはオンザフライで作成されます (少なくとも PHP ではこれを使用しています)。ドキュメントは JSON 形式で生成されます。
サンプル文書
{
"swagger": "2.0",
"info": {
"title": "Company Admin Panel",
"description": "Converting the Magento code into core PHP and RESTful APIs for increasing the performance of the website.",
"contact": {
"email": "[email protected]"
},
"version": "1.0.0"
},
"host": "localhost/cv_admin/api",
"schemes": [
"http"
],
"paths": {
"/getCustomerByEmail.php": {
"post": {
"summary": "List the details of customer by the email.",
"consumes": [
"string",
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "email",
"in": "body",
"description": "Customer email to ge the data",
"required": true,
"schema": {
"properties": {
"id": {
"properties": {
"abc": {
"properties": {
"inner_abc": {
"type": "number",
"default": 1,
"example": 123
}
},
"type": "object"
},
"xyz": {
"type": "string",
"default": "xyz default value",
"example": "xyz example value"
}
},
"type": "object"
}
}
}
}
],
"responses": {
"200": {
"description": "Details of the customer"
},
"400": {
"description": "Email required"
},
"404": {
"description": "Customer does not exist"
},
"default": {
"description": "an \"unexpected\" error"
}
}
}
},
"/getCustomerById.php": {
"get": {
"summary": "List the details of customer by the ID",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Customer ID to get the data",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "Details of the customer"
},
"400": {
"description": "ID required"
},
"404": {
"description": "Customer does not exist"
},
"default": {
"description": "an \"unexpected\" error"
}
}
}
},
"/getShipmentById.php": {
"get": {
"summary": "List the details of shipment by the ID",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Shipment ID to get the data",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "Details of the shipment"
},
"404": {
"description": "Shipment does not exist"
},
"400": {
"description": "ID required"
},
"default": {
"description": "an \"unexpected\" error"
}
}
}
}
},
"definitions": {
}
}
これを次のように Postman にインポートできます。
- Postman UI の左上隅にある「インポート」ボタンをクリックします。
- API ドキュメントをインポートするための複数のオプションが表示されます。「生のテキストを貼り付け」をクリックします。
- テキスト領域に JSON 形式を貼り付けて、インポートをクリックします。
- すべての API が「Postman コレクション」として表示され、Postman から使用できるようになります。
「リンクからのインポート」を使用することもできます。ここでは、Swagger またはその他の API ドキュメント ツールから API の JSON 形式を生成する URL を貼り付けます。
これは私のドキュメント (JSON) 生成ファイルです。PHP で書かれています。JAVA と Swagger についてはよくわかりません。
<?php
require("vendor/autoload.php");
$swagger = \Swagger\scan('path_of_the_directory_to_scan');
header('Content-Type: application/json');
echo $swagger;