CODEWITHSUNDEEP
swaggerswagger-uiopenapi
cnak2
cnak2

Reputation: 1841

Creating sections in swagger

I'm writing a swagger spec and I have three separate endpoints. How do I separate them in my documentation? I want to have a clear distinction between example: Users, Posts & Other. So each one would have a CRUD description and displayed in swagger UI it would look like:

USERS
// user specs

POST
// post specs

OTHER
// other specs

Upvotes: 3

Views: 3949

Answers (1)

mwm
mwm

Reputation: 1973

You need to use tags to accomplish this.

So, on your "paths" object, you sort all your routes and on each one, you add a "tags": ["{resource}"] where it should be grouped.

For example:

"paths": {
    "/users": {
        "get": {
            "tags": ["User"],
            "description": "...",
        },
        "post": {
            "tags": ["User"],
            "description": "...",
        }
    },

    "/posts": {
        "get": {
            "tags": ["Post"],
            "description": "...",
        },
        "post": {
            "tags": ["Post"],
            "description": "...",
        }
    },

    "/other": {
        "get": {
            "tags": ["Other"],
            "description": "...",
        },
        "post": {
            "tags": ["Other"],
            "description": "...",
        }
    },
}

This is not obvious at all on the documentation. Actually the documentation is very complete but lacks an index and some organisation.

Upvotes: 8

Related Questions