Movatterモバイル変換

[0]ホーム
URL:

Skip to content
Join theFastAPI Cloud waiting list 🚀
Follow@fastapi onX (Twitter) to stay updated
FollowFastAPI onLinkedIn to stay updated
Subscribe to theFastAPI and friends newsletter 🎉
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor

Metadata and Docs URLs

You can customize several metadata configurations in yourFastAPI application.

Metadata for API

You can set the following fields that are used in the OpenAPI specification and the automatic API docs UIs:

ParameterTypeDescription
titlestrThe title of the API.
summarystrA short summary of the API.Available since OpenAPI 3.1.0, FastAPI 0.99.0.
descriptionstrA short description of the API. It can use Markdown.
versionstringThe version of the API. This is the version of your own application, not of OpenAPI. For example2.5.0.
terms_of_servicestrA URL to the Terms of Service for the API. If provided, this has to be a URL.
contactdictThe contact information for the exposed API. It can contain several fields.
contact fields
ParameterTypeDescription
namestrThe identifying name of the contact person/organization.
urlstrThe URL pointing to the contact information. MUST be in the format of a URL.
emailstrThe email address of the contact person/organization. MUST be in the format of an email address.
license_infodictThe license information for the exposed API. It can contain several fields.
license_info fields
ParameterTypeDescription
namestrREQUIRED (if alicense_info is set). The license name used for the API.
identifierstrAnSPDX license expression for the API. Theidentifier field is mutually exclusive of theurl field.Available since OpenAPI 3.1.0, FastAPI 0.99.0.
urlstrA URL to the license used for the API. MUST be in the format of a URL.

You can set them as follows:

fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou will be able to:* **Create users** (_not implemented_).* **Read users** (_not implemented_)."""app=FastAPI(title="ChimichangApp",description=description,summary="Deadpool's favorite app. Nuff said.",version="0.0.1",terms_of_service="http://example.com/terms/",contact={"name":"Deadpoolio the Amazing","url":"http://x-force.example.com/contact/","email":"dp@x-force.example.com",},license_info={"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html",},)@app.get("/items/")asyncdefread_items():return[{"name":"Katana"}]

Tip

You can write Markdown in thedescription field and it will be rendered in the output.

With this configuration, the automatic API docs would look like:

License identifier

Since OpenAPI 3.1.0 and FastAPI 0.99.0, you can also set thelicense_info with anidentifier instead of aurl.

For example:

fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou will be able to:* **Create users** (_not implemented_).* **Read users** (_not implemented_)."""app=FastAPI(title="ChimichangApp",description=description,summary="Deadpool's favorite app. Nuff said.",version="0.0.1",terms_of_service="http://example.com/terms/",contact={"name":"Deadpoolio the Amazing","url":"http://x-force.example.com/contact/","email":"dp@x-force.example.com",},license_info={"name":"Apache 2.0","identifier":"Apache-2.0",},)@app.get("/items/")asyncdefread_items():return[{"name":"Katana"}]

Metadata for tags

You can also add additional metadata for the different tags used to group your path operations with the parameteropenapi_tags.

It takes a list containing one dictionary for each tag.

Each dictionary can contain:

  • name (required): astr with the same tag name you use in thetags parameter in yourpath operations andAPIRouters.
  • description: astr with a short description for the tag. It can have Markdown and will be shown in the docs UI.
  • externalDocs: adict describing external documentation with:
    • description: astr with a short description for the external docs.
    • url (required): astr with the URL for the external documentation.

Create metadata for tags

Let's try that in an example with tags forusers anditems.

Create metadata for your tags and pass it to theopenapi_tags parameter:

fromfastapiimportFastAPItags_metadata=[{"name":"users","description":"Operations with users. The **login** logic is also here.",},{"name":"items","description":"Manage items. So _fancy_ they have their own docs.","externalDocs":{"description":"Items external docs","url":"https://fastapi.tiangolo.com/",},},]app=FastAPI(openapi_tags=tags_metadata)@app.get("/users/",tags=["users"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_items():return[{"name":"wand"},{"name":"flying broom"}]

Notice that you can use Markdown inside of the descriptions, for example "login" will be shown in bold (login) and "fancy" will be shown in italics (fancy).

Tip

You don't have to add metadata for all the tags that you use.

Use your tags

Use thetags parameter with yourpath operations (andAPIRouters) to assign them to different tags:

fromfastapiimportFastAPItags_metadata=[{"name":"users","description":"Operations with users. The **login** logic is also here.",},{"name":"items","description":"Manage items. So _fancy_ they have their own docs.","externalDocs":{"description":"Items external docs","url":"https://fastapi.tiangolo.com/",},},]app=FastAPI(openapi_tags=tags_metadata)@app.get("/users/",tags=["users"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_items():return[{"name":"wand"},{"name":"flying broom"}]

Info

Read more about tags inPath Operation Configuration.

Check the docs

Now, if you check the docs, they will show all the additional metadata:

Order of tags

The order of each tag metadata dictionary also defines the order shown in the docs UI.

For example, even thoughusers would go afteritems in alphabetical order, it is shown before them, because we added their metadata as the first dictionary in the list.

OpenAPI URL

By default, the OpenAPI schema is served at/openapi.json.

But you can configure it with the parameteropenapi_url.

For example, to set it to be served at/api/v1/openapi.json:

fromfastapiimportFastAPIapp=FastAPI(openapi_url="/api/v1/openapi.json")@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]

If you want to disable the OpenAPI schema completely you can setopenapi_url=None, that will also disable the documentation user interfaces that use it.

Docs URLs

You can configure the two documentation user interfaces included:

  • Swagger UI: served at/docs.
    • You can set its URL with the parameterdocs_url.
    • You can disable it by settingdocs_url=None.
  • ReDoc: served at/redoc.
    • You can set its URL with the parameterredoc_url.
    • You can disable it by settingredoc_url=None.

For example, to set Swagger UI to be served at/documentation and disable ReDoc:

fromfastapiimportFastAPIapp=FastAPI(docs_url="/documentation",redoc_url=None)@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]
[8]ページ先頭
©2009-2026 Movatter.jp