FastAPI의 메타 데이터 및 추가 응답

가독성을 높이기 위해 고유 한 API 문서 사용자 지정

저자의 사진.

이전 가이드 ( Migrate From Flask to FastAPI Smoothly ) 를 기반으로 오늘 API 문서를 조금 더 살펴 보겠습니다.

이제 생성 된 대화 형 API 문서와 새로 생성 된 FastAPI 서버의 ReDoc이 그다지 직관적이지 않고 입력 및 출력 스키마에 대한 적절한 예제가 부족하다는 것을 깨달아야합니다. 다음 예를 살펴 보겠습니다.

Swagger UI :

작성자 별 이미지

한눈에 두 가지 API를 사용할 수 있음을 추론 할 수 있습니다. 첫 번째 경로는 사용자를 만드는 것이고 두 번째 경로는 새 사용자를 얻는 것입니다. 이 API를 처음 사용하는 사람에게는 정보가 충분하지 않습니다. 게다가 이름은 함수의 실제 이름을 기반으로합니다. 나중에 더 많은 API가 추가 될 때 정말 혼란 스러울 수 있습니다.

API 문서가 다음과 같이 보이면 훨씬 편리하고 설명이 필요하지 않습니다.

작성자 별 이미지

새로운 개발자는 첫 번째 문서에 비해이 문서를 더 쉽게 읽을 수 있습니다.

문서에 메타 데이터를 추가하는 방법에 대한 다음 섹션을 진행하겠습니다.

1. 메타 데이터

태그

문서에 일반 메타 데이터를 추가하는 것은 FastAPI 인스턴스를 초기화 할 때 직접 수행 할 수 있습니다. 그 전에 tags_metadata우리가 가진 각 경로에 대한 설명으로 나중에 사용할 다음 변수를 선언하십시오 .

tags_metadata사전 목록을 포함합니다. 각 사전은 고유 한 이름을 가져야하며 다음 항목으로 구성되어야합니다.

  • name— 태그의 고유 한 이름입니다. 각 사전의 이름으로 경로 이름을 사용하는 것이 좋습니다. 기본적으로 필요합니다.
  • description— 태그에 대한 설명입니다. Markdown 구문을 허용합니다.
  • externalDocs— 두 개의 추가 항목이있는 사전. 첫 번째는 description이고 두 번째 는입니다 (지정된 url경우 필수 externalDocs).

굵게

굵은 단어에는 이중 별표를 사용해야합니다.

The following word is **bolded**.

기울임 꼴의 권장 구문은 텍스트를 별표 하나로 묶는 것입니다.

Flying to *Italy* next week!

다음과 같이 두 가지를 결합 할 수 있습니다.

Have a ***great day*** ahead!

백틱 안에 코드를 묶어 표시 할 수 있습니다.

The code snippet is `userName = 'Wai Foong'`

FastAPI 인스턴스의 일반적인 초기화는 다음과 같습니다.

app = FastAPI()

  • title — 문서 상단에 표시 될 H1 제목을 나타냅니다.
  • description — 제목 바로 아래에 설명 텍스트.
  • version — API의 현재 버전을 나타냅니다.
  • openapi_tags— 각 경로에 대한 메타 데이터가 포함 된 사전 목록입니다. tags_metadata앞서 정의한 변수 를 전달합니다 .

그 후 다음과 같이 경로 내부에 태그를 정의 할 수 있습니다.

@app.post("/create-user", tags=["create-user"])
async def create_user(user: User):
작성자 별 이미지

2. Pydantic BaseModel

새로운 클래스에서 상속하는 PydanticBaseModelFastAPI에서 검증 과정의 핵심 요소로서 작용한다. 기본 개념에 대한 자세한 내용 은 The Beginner 's Guide to Pydantic 을 참조하세요. 또한에서 상속되는 모든 클래스는 추가 메타 데이터를 추가 할 수 BaseModel있는 Request Body인스턴스 역할도합니다 . 일반적으로 다음과 같이 클래스를 정의합니다.

여기에 메타 데이터를 추가하려면 FieldPydantic에서 직접 가져온 클래스 를 사용해야합니다 . 이를 가져 와서 다음 코드 스 니펫으로 함수를 수정하십시오.

선택적 인수의 경우 첫 번째 매개 변수는로 정의되어야합니다 None. 여기 에서는 titleexample매개 변수 만 사용 하고 있습니다.

쿼리, 본문 및 경로

그 외에도에서, 당신은 동일한 인수를 지정할 수 있습니다 Query, BodyPath클래스뿐만 아니라. 유일한 차이점은 Pydantic 대신 FastAPI에서 가져와야한다는 것입니다. 예를 들어 쿼리 매개 변수를 허용하는 다음 경로가 있습니다.

@app.get("/get-user", tags=["get-user"])
async def get_user(id: str):

from fastapi import FastAPI, Query
@app.get("/get-user", tags=["get-user"])
async def get_user(id: str = Query(..., title="3-digit identity number of the user", example="010")):
작성자 별 이미지

또한 입력 페이로드 / 체계에 대한 예제도 업데이트됩니다.

작성자 별 이미지

3. 추가 응답

JSONResponse에서 명시 적으로 언급하지 않는 한 기본적으로 a 가 대답으로 반환됩니다 response_class. 다음 예제는 결과를 일반 텍스트로 반환합니다.

@app.get("/hello", response_class=PlainTextResponse)
async def hello():
    return "Hello World!"

아래 코드 스 니펫은 다음과 같은 경로를 보여줍니다.

  • 상태 코드 200과 일치하는 항목이있는 경우 사용자 정보를 반환합니다.
  • 상태 코드 404를 반환하면 일치하는 항목이 없습니다.
  • 쿼리 매개 변수 ID가 007권한 부족으로 인한 경우 상태 코드 403을 반환합니다 .

  • response_model — 기본 모델을 응답으로 나타냅니다.
  • responses— 키가 상태 코드를 나타내는 사전 형식의 추가 응답. 문서에 표시 할 설명과 예제 결과를 추가 할 수 있습니다.

실제로 미리 정의 된 응답 사전을 만들 수 있습니다.

responses = {
    403: {"model": Message, "description": "Insufficient privileges for this action"},
}

**responses

4. 결론

오늘 배운 내용을 요약 해 보겠습니다.

새로 생성 된 FastAPI 서버에 대한 예제와 설명이 부족하다는 간단한 설명으로 시작했습니다.

다음으로 FastAPI 인스턴스를 초기화 할 때 문서에 메타 데이터를 추가하는 방법을 살펴 보았습니다. 설명 아래에서는 Markdown 구문을 기반으로하는 굵은 체, 기울임 꼴 및 코드를 크게 지원합니다.

다음 섹션으로 이동하여 경로를 추가 title하고 example내부에 적절한 방법을 노출했습니다 . FieldQuery클래스 를 통해 몇 개의 매개 변수에 두 변수를 추가하는 것을 테스트했습니다 .

또한 상태 코드와 함께 추가 응답을 직접 반환하는 방법도 배웠습니다. 라우트 데코레이터 내에 추가 정보를 지정하여 문서에 표시 할 수 있습니다.

이 글을 읽어 주셔서 감사합니다. 다음 기사에서 다시 뵙기를 바랍니다!

참고 문헌

  1. FastAPI 메타 데이터 및 문서
  2. OpenAPI의 FastAPI 추가 응답
  3. FastAPI 스키마 추가
  4. 마크 다운 가이드 기본 구문

Suggested posts

좋은 습관을 만들고 유지하는 방법

장기적인 습관을 유지하기위한 생산성 팁

좋은 습관을 만들고 유지하는 방법

두 아이의 엄마가 된 후 일을 끝내기가 더 어려워졌습니다. 나는 한 작업에서 다음 작업으로 뛰어 들었고 하루가 끝날 때까지 아무것도하지 않았을 때 실망했습니다.

양자 컴퓨팅 Pt를위한 프로그래밍. 1 : NumPy

이제 양자 컴퓨팅이면의 물리학을 배우기 시작 했으므로 "이봐, 실제로 양자 컴퓨터를 사용하려면 실제로 양자 장치를 손으로 만들어야합니까?"라고 궁금해 할 것입니다. 답은 양자 컴퓨터를 컴퓨터라고 부르는 이유가 있습니다. 프로그래밍이 가능합니다! 이 시리즈에서는 수학 개념을 시뮬레이션하고 양자 컴퓨터에서 실행하는 소프트웨어를 구축하는 방법을 배우게됩니다. 깨끗하고 현대적이며 라이브러리가 풍부한 언어이기 때문에 Python을 사용하여 코드를 작성할 것입니다.

Related posts

"실용적인 프로그래머"의 5 가지 필수 사항

역대 베스트셀러 코딩 북의 요점

"실용적인 프로그래머"의 5 가지 필수 사항

Pragmatic Programmer는 1999 년에 처음 출판되었으며 이후 역대 최고의 프로그래밍 책으로 선정되었습니다. 저자 Andy Hunt와 David Thomas는 Agile Manifesto의 원저자 중 하나였으며 몇 가지 심각한 자격을 가지고 있습니다.

대규모 GraphQL 쿼리 공격으로부터 보호

공격자가 공개적으로 사용 가능한 GraphQL 인터페이스를 사용하여 사이트를 스크랩하거나 서비스 거부 공격을 실행하는 방법에 대해 알아보십시오. 이들은 4 가지 방법 중 하나로이를 수행 할 수 있습니다. 단일 대형 쿼리를 신중하게 구성하여 실행하고, 관련 데이터를 가져올 수있는 병렬 쿼리를 많이 작성하고, 일괄 요청을 사용하여 많은 쿼리를 연속적으로 실행하고, 마지막으로 많은 요청을 보냅니다.

기술 인터뷰의 사회적 구성 요소

코딩 문제는 스트레스가 많지만 스트레스에 대한 당신의 반응은 당신의 기술적 능력보다 더 크게 말합니다.

기술 인터뷰의 사회적 구성 요소

기술 업계의 직책을 위해 인터뷰 할 때 일반적으로 제안을 고려하기 전에 최소한 3 차례의 인터뷰를 거치게됩니다. 라운드는 일반적으로 다음과 같습니다. 그렇게 생각하면 잘못된 것입니다.

훌륭한 개발자의 3 가지 행동 특성

훌륭한 개발자의 3 가지 행동 특성

훌륭한 개발자를 만드는 비 기술적 인 것들 나는이 기사를 작성하는 것을 한동안 미루고 있습니다. 나는 그것을 작성할 자격이 있다고 생각하지 못했습니다. 오늘은 쓸 때라고 생각했습니다.