Fastapi: [QUESTION] How to add descriptions to tags?

[timonbimon]

Description

Is there a way to add a description to a tag?

Additional context
Before moving to FastAPI I always had descriptions for my tags in my openapi.yaml

e.g.

tags:
- name: Feedback
  description: Endpoints to give feedback.
- name: Predictions
  description: Endpoints to get predictions.

Is there a way to easily achieve this with FastAPI?

[dmontagu]

It looks like this is not currently possible:

https://github.com/tiangolo/fastapi/blob/580cf8f4e2aac3d4f298fbb3ca1426f9ea6265de/fastapi/openapi/models.py#L214

@timonbimon do you know if this is inconsistent with the OpenAPI spec (ideally, with a reference 😬)? And do you know if it will work properly with Swagger UI / ReDoc? If so, I think it wouldn't be hard to fix.

[dmontagu]

@timonbimon Or maybe you were referring to the tags section at the end of the OpenAPI (see in the same file), which does have those fields. I'm looking now to see if you can set the values properly...

[dmontagu]

It looks like right now there is no built-in way to set these values, but you can add the fields inside a custom openapi-generating function; see these docs for more details.

[timonbimon]

OK awesome, thanks for the quick reply!
I'll use the custom openapi way for now then!

Am Mittwoch, 25. September 2019 schrieb dmontagu [e-mail]:

It looks like right now there is no built-in way to set these values, but
you can add the fields inside a custom openapi-generating function; see these
docs https://fastapi.tiangolo.com/tutorial/extending-openapi/ for more
details.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/tiangolo/fastapi/issues/566?email_source=notifications&email_token=ADQ3SQQCGEXBDLHLIYT5W7DQLK7M3A5CNFSM4I2D6CBKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7QKFBY#issuecomment-534815367,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ADQ3SQQH7X4Y5KCVXU7ROVDQLK7M3ANCNFSM4I2D6CBA
.

[tiangolo]

Thanks for the help @dmontagu!

I think the issue is then solved, right @timonbimon ?

[timonbimon]

hmm I guess it is, even though it would be nice if it were supported out-of-the-box (since it is standard OpenAPI). It's really low priority though I think, so happy to close the issue :)

[shizidushu]

@dmontagu The spec described here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#oasObject and https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#tagObject

Here is the my experiment code following your suggestion. Thanks.

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/", tags=['product', 'service'])
async def read_items():
    return [{"name": "Foo"}]

tags_desc_list = [{"name": "product", "description": "This is description of product tag"}, {"name": "service", "description": "This is description of service tag"}]

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema

    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        description="This is a very custom OpenAPI schema",
        routes=app.routes,
    )

    openapi_schema['tags'] = tags_desc_list

    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

The Swagger UI and ReDoc works too.

I hope FastAPI will implement this spec.

[jeffcarrico]

I too have this issue (and agree it's a minor thing), but hope that it can be supported in FastAPI.

This package is really awesome btw! 👏

[dmontagu]

It looks like this is the actual relevant line (not the one I linked above!): https://github.com/tiangolo/fastapi/blob/580cf8f4e2aac3d4f298fbb3ca1426f9ea6265de/fastapi/openapi/models.py#L351

So I think this is pretty close to being supported. We would just need to add a tags keyword argument to the get_openapi function, and an openapi_tags (or similar) keyword argument to the FastAPI class __init__ function.

If someone would like to submit a PR that adds this functionality (and tests it), I would be happy to review it, and I think it would be worth supporting. (Ultimately, I defer to @tiangolo though!)

[tiangolo]

So, there are 2 tags.

One is the tags parameter in path operation decorators, it has to be a list of strings. That goes in OpenAPI with each path.

And there's also a top-level tags in the OpenAPI schema with a list of objects with extra info about the available tags: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object

So, you would add tags to path operations as normal (as strings), and then you would modify the OpenAPI to include a top level tags with your extra info.

[github-actions[bot]]

Assuming the original issue was solved, it will be automatically closed now. But feel free to add more comments or create new issues.

[thomas-maschler]

@dmontagu if you have the time, I opened a PR to address this issue.

[tiangolo]

Awesome @thomas-maschler ! I just merged it :rocket:

Everyone here, it is now natively supported in FastAPI from version 0.57.0. :tada:

Check the new docs here: https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-tags