41. Metadata and Docs URLs

1. Metadata and Docs URLs

FastAPI 애플리케이션에서 여러 메타데이터 구성을 사용자 지정할 수 있다.

2. Title, description, and version

다음과 같은 것을 설정할 수 있다.

1] Title

OpenAPI 및 자동 API 문서 UI에서 API의 제목/이름으로 사용된다.

2] Description

OpenAPI 및 자동 API 문서 UI의 API에 대한 설명이다.

3] Version

API 버전이다.

이를 설정하려면 다음과 같이 title, description, version 매개변수를 사용하면 된다.

from fastapi import FastAPI

app = FastAPI(
    title="My Super Project",
    description="This is a very fancy project, with auto docs for the API and everything",
    version="2.5.0",
)

@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

위의 예제와 같이 구성하면, 자동 API 문서에서 다음과 같이 표시된다.

3. Metadata for tags

매개변수 openapi_tags를 사용하여 path operation을 그룹화하는 데 사용되는 다양한 태그에 대한 추가 메타데이터를 추가할 수 있다.
각 태그에 대해 하나의 dict 타입을 포함하는 list가 필요하다.
각 dict는 다음과 같은 것을 포함할 수 있다.

1] name(required)

path operation 및 APIRouters의 매개변수 tags에서 사용하는 것과 동일한 태그 이름을 가진 str 타입

2] description

태그에 대한 간단한 설명이 있는 str 타입
Markdown이 있을 수 있으며 문서 UI에 표시된다.

3] externalDocs

외부 문서를 설명하는 사전
description, url(required)

1) Create metadata for tags

users와 items에 대한 태그를 사용해 보자.

다음과 같이 태그에 대한 메타데이터를 생성하고 이를 매개변수 openapi_tags에 전달한다.

from fastapi import FastAPI

tags_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"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]

@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

설명 내에서 Markdown을 사용할 수 있다.

2) Use your tags

path operations와 함께 매개변수 tags를 사용하여 다른 태그에 할당한다.

from fastapi import FastAPI

tags_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"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]

@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

3) Check the docs

문서를 확인하면 다음과 같이 모든 추가 메타데이터가 표시된다.

4) Order of tags

각 태그 메타데이터 dict의 순서는 문서 UI에 표시되는 순서도 정의한다.
예를 들어 users가 사전순으로 items를 찾아보더라도 list의 첫 번째 dict로 메타데이터를 추가했기 때문에 items가 앞에 표시된다.

4. OpenAPI URL

기본적으로 OpenAPI 스키마는 /openapi.json에서 제공된다.
하지만 매개변수 openapi_url을 사용하여 구성할 수 있다.

다음과 같이 /api/v1/openapi.json에서 제공되도록 설정할 수 있다.

from fastapi import FastAPI

app = FastAPI(openapi_url="/api/v1/openapi.json")

@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

OpenAPI 스키마를 완전히 비활성화하려면, openapi_url=None으로 설정하면 된다.

5. Docs URLs

다음과 같은 두 가지 설명서 사용자 인터페이스를 구성할 수 있다.

1] Swagger UI

/docs에서 제공된다.
매개변수 docs_url을 사용하여 URL을 설정할 수 있다.
docs_url=None을 설정하여 비활성화할 수 있다.

2] ReDoc

/redoc에서 제공된다.
매개변수 redoc_url을 사용하여 URL을 설정할 수 있다.
redoc_url=None을 설정하여 비활성화할 수 있다.

다음과 같이 Swagger UI가 /documentation에서 제공되도록 설정하고, ReDoc을 비활성화할 수 있다.

from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url=None)

@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

References

https://fastapi.tiangolo.com/tutorial/metadata/