Question

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.

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.

Answer 1

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

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.

Or look at my examples.

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

}

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