Add description to tags

[Ismael]

Currently the only way to add a description to the tags is to include them manually as "openapi_extra" at the NinjaAPI constructor like so:

api = NinjaAPI(openapi_extra={"tags": [{
    "name": "Account",
    "description": "An Account can have users",
}]})

It would be ideal to be able to add the description to a Router. Something like this maybe:

router = Router(tag="Account", description="An Account can have users")

Or also support externalDocs:

accountTag = Tag("Account", description="An Account can have users", externalDocs_url="http://somewhere", externalDocs_description="A description")
router = Router(tags=[accountTag])

Reference: https://swagger.io/docs/specification/grouping-operations-with-tags/

[vitalik]

Hi @Ismael

you can achieve it with openapi_extra:

api = NinjaAPI(
    openapi_extra={ # < ------
        'tags': [
            {
                'name': 'tag1',
                'description': 'Some description goes here',
            }
        ]
    }
)


@api.post("/hello", tags=["tag1"])
def hello(request):
    return {'hello': 'World'}

technically it's a global record on the whole swagger doc - so I guess it make sense to define it on the NinjaAPI level

[Ismael]

Yes, the feature request is to have a "nicer"? way to do it. Or maybe just document how it's done?

The docs make it sound like using openapi_extra would be to add "weird" stuff. I wasn't that familiar with the spec to know that that was the spot to define tag descriptions.