Static API docs with source2swagger

Question

source2swagger generates a swagger spec with all apis in one json file. Can swagger-ui actually use that? When I explore the generated json file with swagger-ui, it tries to read the api descriptions from their paths in the spec, instead of using the descriptions/operations right there in the single json file.

Answer 1

Swagger-UI will handle putting all the json in one file. I'm not sure yet if there can be multiple top-level resource listings though.

Here's a working example:

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