招摇着静态文档(Swagger With Static Documentation)

2019-06-24 08:31发布

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

我期待用扬鞭来记录我的RESTful接口。 问题是，我不希望被标注我的代码自动生成我的文档。 基本上我不希望我的几个内部数据模型，通过接口暴露的虚拟数据模型。 看来，我可以有我的服务器为每个资源处理程序Resources.json文件，然后相应的JSON文件。 然而，当我尝试这样做我遇到了很多小陷阱，而试图定义JSON正确的语法，并提供正确的HTTP标头响应字段。

曾用扬鞭这样的人？ 任何人有一些文档或例子？ 一切，我可以简单地使用客户端库生成的东西为您找到围绕着。

Answer 1:

我创建静态JSON文件招摇了。 该文档是有点缺乏描述获得招摇工作所需的JSON。

如果你看看他们的天赋 ，看看他们的榜样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": [ ]
                }
            ]
        },
    ]
}


Answer 2:

我一直在使用PHP招摇这里是我的代码，如果有人想要创建JSON从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代码招摇的用户界面： 

 {
"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的路径



文章来源: Swagger With Static Documentation
标签： rest documentation-generation swagger
举报

收藏的人(0)

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