Swagger со статической документацией

Я хочу использовать Swagger для документирования моего спокойного интерфейса. Проблема в том, что я не хочу автоматически генерировать мою документацию, аннотируя мой код. В принципе, я не хочу связывать свою внутреннюю модель данных с виртуальной моделью данных, открытой интерфейсом. Похоже, что я могу просто предоставить серверу файл Resource.json, а затем соответствующий JSON файл для каждого обработчика ресурсов. Тем не менее, когда я это пробовал, я столкнулся с множеством мелких ошибок, пытаясь определить правильный синтаксис JSON и предоставить правильные поля ответа HTTP-заголовка.

Кто-нибудь использовал Swagger таким образом? У кого-нибудь есть документация или примеры? Все, что я мог найти, сосредоточилось на простое использование клиентских библиотек для генерации вещей для вас.

ОТВЕТЫ

Ответ 1

Я создал статические файлы json для swagger. Документация не нуждается в описании json, требуемой для того, чтобы заставить swagger работать.

Если вы посмотрите на 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": [ ]
                }
            ]
        },
    ]
}

Ответ 2

Я создал json из файлов PHP, используя swagger PHP, вот мой код, если кто-то ищет, надеюсь, что он поможет

<?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;



 }

}

вот код JSON для swagger UI:

 {
"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"
]
}

Дайте путь json в api-doc.json