静的なドキュメントでSwagger
Swaggerを使用して、落ち着いたインターフェースを文書化したいと考えています。問題は、コードに注釈を付けてドキュメントを自動的に生成したくないことです。基本的に、内部データモデルを、インターフェイスによって公開される仮想データモデルに結合したくありません。サーバーにResources.jsonファイルを提供させ、次に各リソースハンドラーに対応するJSONファイルを提供させるだけのようです。しかし、これを試したところ、JSONの正しい構文を定義し、正しいHTTPヘッダー応答フィールドを提供しようとするときに、多くの小さな問題に遭遇しました。
誰かがこのようにSwaggerを使用しましたか？誰かがドキュメントや例を持っていますか？クライアントライブラリを使用して物事を生成することを中心に、私が見つけることができるすべてのものを集めました。
以前、swagger用の静的jsonファイルを作成しました。ドキュメントは、swaggerを動作させるために必要なjsonを説明するのに少し欠けています。
それらの spec を見て、例 petstore.json を見てください。あなたはあなたのjsonをどのように構成するかについてかなり良い考えを得ることができるはずです。
または私の例を見てください。
他にご不明な点がございましたら、お気軽にお問い合わせください。
main.json
{
"apiVersion": "0.0.4542.22887",
"swaggerVersion": "1.0",
"basePath": "http://local.api.com/api/doc",
"apis": [
{
"path": "/donuts",
"description": "Operations about donuts"
},
{
"path": "/cakes",
"description": "Operations about cakes"
},
{
"path": "/bagels",
"description": "Operations about bagels"
}
]
}
donuts.json
{
"apiVersion": "0.0.4542.22887",
"swaggerVersion": "1.0",
"basePath": "http://local.api.com/api",
"resourcePath": "/donuts",
"apis": [
{
"path": "/donuts/{page}/{pagesize}",
"description": "Get donuts by page",
"operations": [
{
"httpMethod": "GET",
"notes": "Get a donut with page and size",
"nickname": "getDonutsByPageAndSize",
"summary": "Get a collection of donuts by page and pagesize.",
"parameters": [
{
"name": "page",
"description": "the page of the collection",
"dataType": "int",
"required": true,
"allowMultiple": false,
"paramType": "path"
},
{
"name": "pagesize",
"description": "the size of the collection",
"dataType": "int",
"required": true,
"allowMultiple": false,
"paramType": "path"
}
],
"errorResponses": [ ]
}
]
},
]
}
PHP swaggerを使用したファイルPHP=からjsonを作成しました。
<?php
namespace carParking\Resources;
use Swagger\Annotations as SWG;
/**
* @package
* @category
* @subpackage
*
* @SWG\Resource(
* apiVersion="1.0.0",
* swaggerVersion="1.2",
* basePath="http://192.168.3.42/swagger/api",
* resourcePath="/car",
* description="Car Parking System",
* produces="['application/json','application/xml','text/plain','text/html']"
* )
*/
class Car
{
/**
* @SWG\Api(
* path="/car/car.php?carId={carId}",
* @SWG\Operation(
* method="GET",
* summary="Find car by ID",
* notes="Returns a car based on ID",
* type="Car",
* nickname= "getCarById",
* authorizations={},
* @SWG\Parameter(
* name="carId",
* description="ID of car that needs to be fetched",
* required=true,
* type="integer",
* format="int64",
* paramType="path",
* allowMultiple=false
* ),
* @SWG\ResponseMessage(code=400, message="Invalid ID supplied"),
* @SWG\ResponseMessage(code=404, message="car not found")
* )
* )
*/
public function getCarById() {
echo "getCarById";
}
/**
* @SWG\Api(
* path="/car/fetchAll.php",
* @SWG\Operation(
* method="GET",
* summary="Fetch all parked cars",
* notes="Returns all cars parked",
* type="Car",
* nickname= "getAllParkedCars",
* authorizations={},
* @SWG\ResponseMessage(code=404, message="car not found")
* )
* )
*/
public function getAllParkedCars() {
echo "getAllParkedCars";
}
/**
* @SWG\Api(
* path="/car/delete.php",
* @SWG\Operation(
* method="DELETE",
* summary="Deletes a Car",
* notes="Delete a parked car",
* type="void",
* nickname= "deleteCar",
* @SWG\Consumes("application/x-www-form-urlencoded"),
* authorizations={},
* @SWG\Parameter(
* name="carId",
* description="ID of car that needs to be deleted",
* required=true,
* type="integer",
* format="int64",
* paramType="form",
* allowMultiple=false
* ),
* @SWG\ResponseMessage(code=400, message="Invalid ID supplied"),
* @SWG\ResponseMessage(code=404, message="car not found")
* )
* )
*/
public function deleteCar() {
echo "deleteCar";
}
/**
* @SWG\Api(
* path="/car/add.php",
* @SWG\Operation(
* method="POST",
* summary="Add Car",
* notes="Add car to parking",
* type="array",
* @SWG\Items("car"),
* nickname= "addCar",
* authorizations={},
* @SWG\Parameter(
* name="parking_section_id",
* description="Parking Area ID",
* required=true,
* type="integer",
* format="int64",
* paramType="form",
* allowMultiple=false
* ),
* @SWG\Parameter(
* name="car_number",
* description="Car Number",
* required=true,
* type="integer",
* format="int64",
* paramType="form",
* allowMultiple=false
* ),
* @SWG\Parameter(
* name="cost",
* description="Cost of Parking",
* required=true,
* type="integer",
* format="int64",
* paramType="form",
* allowMultiple=false
* ),
* @SWG\ResponseMessage(code=400, message="Invalid ID supplied"),
* @SWG\ResponseMessage(code=404, message="car not found")
* )
* )
*/
public function addCar() {
echo "addCar";
}
/**
* @SWG\Api(
* path="/car/getCost.php",
* @SWG\Operation(
* method="POST",
* summary="Parking Cost of the Car Parked",
* notes="Parking Cost of the Car Parked",
* type="void",
* nickname= "getCost",
* authorizations={},
* @SWG\Parameter(
* name="carId",
* description="Parking Area ID",
* required=true,
* type="integer",
* format="int64",
* paramType="form",
* allowMultiple=false
* ),
* @SWG\ResponseMessage(code=405, message="Invalid input")
* )
* )
*/
public function getCost() {
echo "getCost";
}
/**
* @SWG\Api(
* path="/car/deleteAll.php",
* @SWG\Operation(
* method="DELETE",
* summary="Delete all car parking",
* notes="Delete all car parking",
* type="void",
* nickname= "deleteAll",
* @SWG\Consumes("application/x-www-form-urlencoded"),
* authorizations={}
* )
* )
*/
public function deleteAll() {
echo "deleteAll";
}
/**
* @SWG\Api(
* path="/car/testPut.php",
* @SWG\Operation(
* method="PUT",
* summary="Testing Put",
* notes="Testing Put",
* type="void",
* nickname= "testWithFormPut",
* @SWG\Consumes("application/x-www-form-urlencoded"),
* authorizations={},
* @SWG\Parameter(
* name="firstPara",
* description="First Parameter",
* required=true,
* type="integer",
* format="int64",
* paramType="form",
* allowMultiple=false
* ),
* @SWG\Parameter(
* name="secondPara",
* description="Second Parameter",
* required=true,
* type="integer",
* format="int64",
* paramType="form",
* allowMultiple=false
* ),
* @SWG\ResponseMessage(code=405, message="Invalid input")
* )
* )
*/
public function testWithFormPut() {
echo "testWithFormPut";
}
/**
* @SWG\Api(
* path="/car/testPatch.php",
* @SWG\Operation(
* method="PATCH",
* summary="Testing Patch",
* notes="Testing Patch",
* type="void",
* nickname= "testWithFormPatch",
* @SWG\Consumes("application/x-www-form-urlencoded"),
* authorizations={},
* @SWG\Parameter(
* name="firstPara",
* description="First Parameter",
* required=true,
* type="integer",
* format="int64",
* paramType="form",
* allowMultiple=false
* ),
* @SWG\Parameter(
* name="secondPara",
* description="Second Parameter",
* required=true,
* type="integer",
* format="int64",
* paramType="form",
* allowMultiple=false
* ),
* @SWG\ResponseMessage(code=405, message="Invalid input")
* )
* )
*/
public function testWithFormPatch() {
echo "testWithFormPatch";
}
/**
* @SWG\Api(
* path="/car/carJsonTest.php",
* @SWG\Operation(
* method="POST",
* summary="Send and parse JSON",
* notes="Send and parse JSON",
* type="void",
* authorizations={},
* @SWG\Parameter(
* name="body",
* description="Sample JSON need to be passed",
* required=true,
* type="Car",
* paramType="body",
* allowMultiple=false
* ),
* @SWG\ResponseMessage(code=405, message="Invalid input")
* )
* )
*/
public function carJsonTest() {
echo "carJsonTest";
}
モデルコード：
<?php
namespace carStore\Models;
use Swagger\Annotations as SWG;
/**
* @package
* @category
* @subpackage
*
* @SWG\Model(id="Car",required="parking_section_id, car_number, cost")
*/
class Car
{
/**
* @SWG\Property(name="parking_section_id",type="integer",format="int64",minimum="0.0",maximum="100.0",description="unique identifier for the parking")
*/
public $parking_section_id;
/**
* @SWG\Property(name="car_number",type="integer",format="int64",description="unique identifier for the car")
*/
public $car_number;
/**
* @SWG\Property(name="cost",type="integer",format="int64",description="cost for the parking")
*/
public $cost;
}
}
ここにSwagger UIのJSONコードを示します。
{
"basePath": "http://192.168.3.42/swagger/api",
"swaggerVersion": "1.2",
"apiVersion": "1.0.0",
"resourcePath": "/car",
"apis": [
{
"path": "/car/add.php",
"operations": [
{
"method": "POST",
"summary": "Add Car",
"nickname": "addCar",
"type": "array",
"items": {
"$ref": "car"
},
"parameters": [
{
"paramType": "form",
"name": "parking_section_id",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "Parking Area ID",
"format": "int64"
},
{
"paramType": "form",
"name": "car_number",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "Car Number",
"format": "int64"
},
{
"paramType": "form",
"name": "cost",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "Cost of Parking",
"format": "int64"
}
],
"responseMessages": [
{
"code": 400,
"message": "Invalid ID supplied"
},
{
"code": 404,
"message": "car not found"
}
],
"notes": "Add car to parking",
"authorizations": {
}
}
]
},
{
"path": "/car/car.php?carId={carId}",
"operations": [
{
"method": "GET",
"summary": "Find car by ID",
"nickname": "getCarById",
"type": "Car",
"parameters": [
{
"paramType": "path",
"name": "carId",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "ID of car that needs to be fetched",
"format": "int64"
}
],
"responseMessages": [
{
"code": 400,
"message": "Invalid ID supplied"
},
{
"code": 404,
"message": "car not found"
}
],
"notes": "Returns a car based on ID",
"authorizations": {
}
}
]
},
{
"path": "/car/carJsonTest.php",
"operations": [
{
"method": "POST",
"summary": "Send and parse JSON",
"nickname": "carJsonTest",
"type": "void",
"parameters": [
{
"paramType": "body",
"name": "body",
"type": "Car",
"required": true,
"allowMultiple": false,
"description": "Sample JSON need to be passed"
}
],
"responseMessages": [
{
"code": 405,
"message": "Invalid input"
}
],
"notes": "Send and parse JSON",
"authorizations": {
}
}
]
},
{
"path": "/car/delete.php",
"operations": [
{
"method": "DELETE",
"summary": "Deletes a Car",
"nickname": "deleteCar",
"type": "void",
"parameters": [
{
"paramType": "form",
"name": "carId",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "ID of car that needs to be deleted",
"format": "int64"
}
],
"responseMessages": [
{
"code": 400,
"message": "Invalid ID supplied"
},
{
"code": 404,
"message": "car not found"
}
],
"notes": "Delete a parked car",
"consumes": [
"application/x-www-form-urlencoded"
],
"authorizations": {
}
}
]
},
{
"path": "/car/deleteAll.php",
"operations": [
{
"method": "DELETE",
"summary": "Delete all car parking",
"nickname": "deleteAll",
"type": "void",
"notes": "Delete all car parking",
"consumes": [
"application/x-www-form-urlencoded"
],
"authorizations": {
}
}
]
},
{
"path": "/car/fetchAll.php",
"operations": [
{
"method": "GET",
"summary": "Fetch all parked cars",
"nickname": "getAllParkedCars",
"type": "Car",
"responseMessages": [
{
"code": 404,
"message": "car not found"
}
],
"notes": "Returns all cars parked",
"authorizations": {
}
}
]
},
{
"path": "/car/getCost.php",
"operations": [
{
"method": "POST",
"summary": "Parking Cost of the Car Parked",
"nickname": "getCost",
"type": "void",
"parameters": [
{
"paramType": "form",
"name": "carId",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "Parking Area ID",
"format": "int64"
}
],
"responseMessages": [
{
"code": 405,
"message": "Invalid input"
}
],
"notes": "Parking Cost of the Car Parked",
"authorizations": {
}
}
]
},
{
"path": "/car/testPatch.php",
"operations": [
{
"method": "PATCH",
"summary": "Testing Patch",
"nickname": "testWithFormPatch",
"type": "void",
"parameters": [
{
"paramType": "form",
"name": "firstPara",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "First Parameter",
"format": "int64"
},
{
"paramType": "form",
"name": "secondPara",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "Second Parameter",
"format": "int64"
}
],
"responseMessages": [
{
"code": 405,
"message": "Invalid input"
}
],
"notes": "Testing Patch",
"consumes": [
"application/x-www-form-urlencoded"
],
"authorizations": {
}
}
]
},
{
"path": "/car/testPut.php",
"operations": [
{
"method": "PUT",
"summary": "Testing Put",
"nickname": "testWithFormPut",
"type": "void",
"parameters": [
{
"paramType": "form",
"name": "firstPara",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "First Parameter",
"format": "int64"
},
{
"paramType": "form",
"name": "secondPara",
"type": "integer",
"required": true,
"allowMultiple": false,
"description": "Second Parameter",
"format": "int64"
}
],
"responseMessages": [
{
"code": 405,
"message": "Invalid input"
}
],
"notes": "Testing Put",
"consumes": [
"application/x-www-form-urlencoded"
],
"authorizations": {
}
}
]
}
],
"models": {
"Car": {
"id": "Car",
"required": [
"car_number",
"cost",
"parking_section_id"
],
"properties": {
"parking_section_id": {
"description": "unique identifier for the parking",
"type": "integer",
"format": "int64",
"minimum": "0.0",
"maximum": "100.0"
},
"car_number": {
"description": "unique identifier for the car",
"type": "integer",
"format": "int64"
},
"cost": {
"description": "cost for the parking",
"type": "integer",
"format": "int64"
}
}
}
},
"produces": [
"application/json",
"application/xml",
"text/plain",
"text/html"
]
}
Api-doc.jsonでjsonパスを指定します