FastAPI – @Schema(hidden=True) not working when trying to hide the schema section on swagger docs
Question:
I’m trying to hide the entire schemas section of the FastAPI generated swagger docs. I’ve checked the docs and tried this but the schema section still shows.
@Schema(hidden=True)
class theSchema(BaseModel):
category: str
How do I omit one particular schema or the entire schemas section from the returned swagger docs.
docExpansion does not appear to work either. What am I missing?
app = FastAPI(
openapi_tags=tags_metadata,
title="Documentation",
description="API endpoints",
version="0.1",
docExpansion="None"
)
Answers:
set include_in_schema=False in the args to the FastAPI instance decorator instead
app = FastAPI(...)
@app.get("/", include_in_schema=False)
async def root():
...
Not sure if I get points for answering my own question but if anyone wants to know, this was resolved by loading the swagger page into an iframe then using js to hide the desired elements within that document’s iframe.
swagger has the UI parameter "defaultModelsExpandDepth" for controlling models’ view in the schema section.
This parameter can be forwarded using "swagger_ui_parameters" parameter on FastApi initialization.
app = FastAPI(swagger_ui_parameters={"defaultModelsExpandDepth": -1})
Values:
- -1: schema section hidden
- 0: schema section is closed
- 1: schema section is open (default)
More options can be found here: https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
I had a similar requirement where I wanted to exclude certain schemas including "Enum" schemas as well. The only way I was able to do it was to generate custom OpenAPI schema as explained in FastAPI docs.
First, you use the "schema_extra" pydantic Model Config to add a hidden field in generated json. This can be found in pydantic’s documentation.
class ModelA(BaseModel):
Field1: int | None = None
Field2: str | None = None
class Config:
schema_extra = {"hidden": True}
Then you can generate the custom OpenAPI schema using,
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="My app",
version="1.0",
description="My app's description",
routes=app.routes,
)
if "components" in openapi_schema:
# I used jsonref to dereference related schemas
# You will need to install jsonref
dereferenced_schema = jsonref.loads(json.dumps(openapi_schema), lazy_load=False)
openapi_schema["components"] = jsonable_encoder(dereferenced_schema["components"])
for schema_name in openapi_schema["components"]["schemas"].copy().keys():
schema = openapi_schema["components"]["schemas"][schema_name]
if "enum" in schema:
print(f"Removing {schema_name} as it is an enum")
del openapi_schema["components"]["schemas"][schema_name]
continue
hide = schema.get("hidden", False)
if hide:
print(f"Removing {schema_name} as it is hidden")
del openapi_schema["components"]["schemas"][schema_name]
continue
app.openapi_schema = openapi_schema
return app.openapi_schema
Finally, assign this custom function to your FastAPI app’s openapi funciton as-
app.openapi = custom_openapi
Hope this helps.
I’m trying to hide the entire schemas section of the FastAPI generated swagger docs. I’ve checked the docs and tried this but the schema section still shows.
@Schema(hidden=True)
class theSchema(BaseModel):
category: str
How do I omit one particular schema or the entire schemas section from the returned swagger docs.
docExpansion does not appear to work either. What am I missing?
app = FastAPI(
openapi_tags=tags_metadata,
title="Documentation",
description="API endpoints",
version="0.1",
docExpansion="None"
)
set include_in_schema=False in the args to the FastAPI instance decorator instead
app = FastAPI(...)
@app.get("/", include_in_schema=False)
async def root():
...
Not sure if I get points for answering my own question but if anyone wants to know, this was resolved by loading the swagger page into an iframe then using js to hide the desired elements within that document’s iframe.
swagger has the UI parameter "defaultModelsExpandDepth" for controlling models’ view in the schema section.
This parameter can be forwarded using "swagger_ui_parameters" parameter on FastApi initialization.
app = FastAPI(swagger_ui_parameters={"defaultModelsExpandDepth": -1})
Values:
- -1: schema section hidden
- 0: schema section is closed
- 1: schema section is open (default)
More options can be found here: https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
I had a similar requirement where I wanted to exclude certain schemas including "Enum" schemas as well. The only way I was able to do it was to generate custom OpenAPI schema as explained in FastAPI docs.
First, you use the "schema_extra" pydantic Model Config to add a hidden field in generated json. This can be found in pydantic’s documentation.
class ModelA(BaseModel):
Field1: int | None = None
Field2: str | None = None
class Config:
schema_extra = {"hidden": True}
Then you can generate the custom OpenAPI schema using,
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="My app",
version="1.0",
description="My app's description",
routes=app.routes,
)
if "components" in openapi_schema:
# I used jsonref to dereference related schemas
# You will need to install jsonref
dereferenced_schema = jsonref.loads(json.dumps(openapi_schema), lazy_load=False)
openapi_schema["components"] = jsonable_encoder(dereferenced_schema["components"])
for schema_name in openapi_schema["components"]["schemas"].copy().keys():
schema = openapi_schema["components"]["schemas"][schema_name]
if "enum" in schema:
print(f"Removing {schema_name} as it is an enum")
del openapi_schema["components"]["schemas"][schema_name]
continue
hide = schema.get("hidden", False)
if hide:
print(f"Removing {schema_name} as it is hidden")
del openapi_schema["components"]["schemas"][schema_name]
continue
app.openapi_schema = openapi_schema
return app.openapi_schema
Finally, assign this custom function to your FastAPI app’s openapi funciton as-
app.openapi = custom_openapi
Hope this helps.