Generate OpenApi documentation filtered by Route tags

[romulorosa]

First check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.
• After submitting this, I commit to:
  • Read open issues with questions until I find 2 issues where I can help someone and add a comment to help there.
  • Or, I already hit the "watch" button in this repository to receive notifications and I commit to help at least 2 people that ask questions in the future.
  • Implement a Pull Request for a confirmed bug.

Description

This is useful when I don't wanna have multiple apps but I wanna create different docs for each route label. This allows me to create independent files and organize then into my documentation index in a more free way.

A specific use case. Let's say that I have two versions of my APL (api v1 and api v2) and I have it under the same app but I tagged all my endpoints with their correspondent version. Having that, I want to create different doc files for each of them and expose them in a different section in my documentation index page.

So, I would like to be able to:

• Generate OpenAPI docs filtered by route tags
• Returns documentation only about the filtered routes.

Proposal

My idea is to create a function into class FastAPI which returns routes based in its tags (it can actually be even more generic) and change openapi method (https://github.com/tiangolo/fastapi/blob/master/fastapi/applications.py#L128) signature to receive an extra argument containing a list of tags which should be filtered. My initial proposition is

applications.py

class FastAPI(Starlette):
  [...]

    def routes_by_tag(self, tags: typing.List[str] = None) -> typing.List[BaseRoute]:
        routes = self.routes
        if not tag:
            return routes
        tags_set = set(tags)
        return [route for route in routes if tags_set.intersection(set(route.tags))]

  def openapi(self, route_tags: typing.Optional[typing.List[str]]) -> Dict:
          if not self.openapi_schema:
              self.openapi_schema = get_openapi(
                  title=self.title,
                  version=self.version,
                  openapi_version=self.openapi_version,
                  description=self.description,
                  routes=self.routes_by_tag(route_tags),
                  tags=self.openapi_tags,
                  servers=self.servers,
              )
          return self.openapi_schema

And then I can call openapi like below:

filtered_doc = app.openapi(route_tags=["my_tag"])

[Kludex]

For the time being: #3047 (comment)

I like the idea (not the way it is implemented above). But adding filter parameters on the openapi() function looks useful.

[romulorosa]

@Kludex What would you suggest instead?

[Kludex]

But adding filter parameters on the openapi() function looks useful.

Nothing specific, but additional parameters only, not removing what is already in place. 😗

[lsmith77]

would also love to have this since we want to only share part of our API with outside partners.

[JLHasson]

FWIW you can filter which routes are included in the OpenAPI schema using the include_in_schema parameter on the route definition:

@app.get("/", include_in_schema=False)
async def root():
    return {"hello": "world"}

[scottluskcis]

Working on a project that has this same need, curious if others have identified a solution for this.