Swagger与静态文档

Question

我希望使用Swagger记录我的restful接口.问题是我不想通过注释我的代码来自动生成我的文档.基本上我不想将我的内部数据模型耦合到接口公开的虚拟数据模型.看来我可以让我的服务器提供一个Resources.json文件,然后为每个资源处理程序提供相应的JSON文件.但是,当我尝试这个时,我试图定义JSON正确的语法并提供正确的HTTP头响应字段时遇到了很多小问题.

有没有人用这种方式使用Swagger？有人有一些文件或例子吗？我能找到的所有内容都只是使用客户端库为您生成内容.

Answer 1

我以前为swagger创建了静态json文件.文档有点缺乏描述json所需的swson工作.

如果你查看他们的规范并查看他们的示例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": [ ]
                }
            ]
        },
    ]
}