Fastapi: Is there a way to hide some fields from OpenAPI specs?

[mclate]

First check

• [x] I added a very descriptive title to this issue.
• [x] I used the GitHub search to find a similar issue and didn't find it.
• [x] I searched the FastAPI documentation, with the integrated search.
• [x] I already searched in Google "How to X in FastAPI" and didn't find any information.
• [x] I already read and followed all the tutorial in the docs and didn't find an answer.
• [x] I already checked if it is not related to FastAPI but to Pydantic.
• [x] I already checked if it is not related to FastAPI but to Swagger UI.
• [x] I already checked if it is not related to FastAPI but to ReDoc.
• [x] After submitting this, I commit to one of:
  
  
  
  • Read open issues with questions until I find 2 issues where I can help someone and add a comment to help there.
  
  
  • 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.
  
  

Example

Here's a self-contained, minimal, reproducible, example with my use case:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root(hidden_param=Query(None, description="This parameter should not be visible in OpenApi specs")):
    if hidden_param:
        return {"Hello": "Master!"}
    else:
        return {"Hello": "World"}

Description

I'd like to have some request parameters (query or body ones) to be available in the python code, but to be hidden from the OpenAPI specs. Wonder if it is possible to do?

[tiangolo]

Hmm, interesting...

I guess we could have a parameter include_in_schema for Query, Body, etc, something like:

from fastapi import FastAPI, Query, Body
from pydantic import BaseModel

app = FastAPI()


@app.get("/")
def read_root(hidden_param: str = Query(None, include_in_schema=False)):
    if hidden_param:
        return {"Hello": "Master!"}
    else:
        return {"Hello": "World"}


class Item(BaseModel):
    name: str
    price: float


@app.post("/items/")
def create_item(item: Item = Body(None, include_in_schema=False)):
    return item

---

BTW, if you want to selectively remove or alter things from the schema for a Pydantic model you can already do that with schema_extra: https://pydantic-docs.helpmanual.io/usage/schema/#schema-customization

[roeeyn]

Cool @tiangolo, I will give it a try 😄

[itssimon]

I would also be interested in an include_in_schema argument for Query, Body etc.

[Gatux]

It may also be useful with Header to hide x-forwarded-for from the documentation for example, when FastAPI is used behind a reverse proxy.

[mnorrsken]

I would like this feature too. We have a header with auth info thats always sent from our API manager to our backend. I want to consume this header in my API but I don't want it to show up in the docs.

[dvarrazzo]

Another use case: testing. In order to test the expiry of a session I use an header parameter and pass a short timeout to test for session expiry:

async def login(auth: AuthForm, x_session_timeout_sec: Optional[float] = Header(None)) -> LoginResponse:
    kw = {}
    conf = get_config()
    if conf.testing:
        kw["timeout_sec"] = x_session_timeout_sec

    await create_session(user_data, **kw)
    ...

the use of such parameter can be disabled in production, testing it against env vars, but it's not easy to change the signature of the python function based on env vars, and changing the openapi.json for every such use is pretty cumbersome.

[mnorrsken]

I have got around it by using a Depends which looks at the request directly so its not showing the parameter in documentation.