使用静态文档大摇大摆 [英] Swagger With Static Documentation

问题描述

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

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.

有人以这种方式使用过 Swagger 吗?有人有一些文档或示例吗?我能找到的一切都围绕着简单地使用客户端库为您生成东西.

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.

推荐答案

我之前为 swagger 创建了静态 json 文件.该文档有点缺乏描述使招摇工作所需的json.

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

如果您查看他们的 spec 并查看他们的示例 petstore.json.您应该能够很好地了解如何构建 json.

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.

或者看看我的例子.

如果您还有其他问题，请随时提出.

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

}

甜甜圈.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": [ ]
                }
            ]
        },
    ]
}

这篇关于使用静态文档大摇大摆的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！