swagger - 使用 source2swagger 的静态 API 文档

Question

source2swagger 在一个 json 文件中生成一个包含所有 api 的 swagger 规范。swagger-ui 真的可以使用它吗？当我使用 swagger-ui 探索生成的 json 文件时，它会尝试从规范中的路径读取 api 描述，而不是使用单个 json 文件中的描述/操作。

Answer 1

Swagger-UI 将处理将所有 json 放在一个文件中。我还不确定是否可以有多个顶级资源列表。

这是一个工作示例：

{"basePath":"http://localhost:3001/", "resourcePath":"/", "swaggerVersion":"1.1", "apiVersion":"1.0", "apis":[
    {
        "path":"/pay",
        "format":"json",
        "description":"Create a transaction with the given amount and token.",
        "operations":[
            {
                "httpMethod":"GET",
                "tags":["production"],
                "nickname":"pay",
                "deprecated":false,
                "summary":"Create a transaction with the given amount and token.",
                "parameters":[
                    {
                        "name":"token",
                        "description":"The token representing the pay card",
                        "dataType":"string",
                        "allowMultiple":false,
                        "required":true,
                        "paramType":"query"
                    },
                    {
                        "name":"amount",
                        "description":"The amount to pay",
                        "dataType":"string",
                        "allowMultiple":false,
                        "required":true,
                        "paramType":"query"
                    }
                ]
            }
        ]
    },
    {
        "path":"/customer",
        "format":"json",
        "description":"Create an HTML form for adding a customer.",
        "operations":[
            {
                "httpMethod":"GET",
                "tags":["production"],
                "nickname":"createCustomerForm",
                "deprecated":false,
                "summary":"Create an HTML form for adding a customer.",
                "parameters":[
                    {
                        "name":"customerId",
                        "description":"Your customer id",
                        "dataType":"string",
                        "allowMultiple":false,
                        "required":true,
                        "paramType":"query"
                    }
                ]
            }
        ]
    },
    {
        "path":"/customer/{customerId}",
        "format":"json",
        "description":"Delete the customer info for given id.",
        "operations":[
            {
                "httpMethod":"DELETE",
                "tags":["production"],
                "nickname":"deleteCustomer",
                "deprecated":false,
                "summary":"Delete the customer info for given id.",
                "parameters":[
                    {
                        "name":"customerId",
                        "description":"the customer id to delete",
                        "dataType":"string",
                        "allowMultiple":false,
                        "required":true,
                        "paramType":"path"
                    }
                ]
            }
        ]
    },
    {
        "path":"/card",
        "format":"json",
        "description":"Create an HTML form for adding a credit card.",
        "operations":[
            {
                "httpMethod":"GET",
                "tags":["production"],
                "nickname":"createCardForm",
                "deprecated":false,
                "summary":"Create an HTML form for the given customer to add a credit card.",
                "parameters":[
                    {
                        "name":"customerId",
                        "description":"Your customer id",
                        "dataType":"string",
                        "allowMultiple":false,
                        "required":true,
                        "paramType":"query"
                    }
                ]
            }
        ]
    },
    {
        "path":"/card/{token}",
        "format":"json",
        "description":"Delete a card record by token.",
        "operations":[
            {
                "httpMethod":"DELETE",
                "tags":["production"],
                "nickname":"deleteCard",
                "deprecated":false,
                "summary":"Delete the card info for given token.",
                "parameters":[
                    {
                        "name":"token",
                        "description":"the token to delete",
                        "dataType":"string",
                        "allowMultiple":false,
                        "required":true,
                        "paramType":"path"
                    }
                ]
            }
        ]
    }
]}