Static API docs with source2swagger - swagger

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