Swagger With Static Documentation

2019-01-30 07:19发布

站内文章 / 前沿技术
22 0 0

问题:

I am looking to use Swagger to document my restful interface. The problem is that I do not want to automatically generate my documentation by annotating my code. Basically I don't want to couple my internal data model to the virtual data model exposed by the interface. It appears that I can just have my server provide a Resources.json file and then a corresponding JSON file for each resource handler. However, when I tried this I ran into lots of little gotchas while attempting to define the JSON correct syntax and provide the correct HTTP header response fields.

Has anyone used Swagger in this way? Anyone have some documentation or examples? Everything that I could find centered around simply using the client libraries to generate things for you.

回答1:

I've created static json files for swagger before. The documentation is kinda lacking in describing the json required to get swagger to work.

If you look at their spec and look at their example petstore.json. You should be able to get a pretty good idea of how to structure your json.

Or look at my examples.

If you have any more questions feel free to ask.

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:

I have created json from PHP files using swagger PHP here is my code if anyone is looking for, hope it helps

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

Model code: 

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



 }

}

here us JSON code for 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"
]
}

Give the json path in api-doc.json



标签： rest documentation-generation swagger
举报

收藏的人(0)

Ta的文章 更多文章
登录 后发表评论
0条评论
还没有人评论过~