[ FastAPI ] 경로 동작 구성

아래는 경로 동작 데코레이터를 구성할 때 전달할 수 있는 매개변수들입니다.

 

주의

이 매개변수들은 경로 동작 함수가 아닌, 경로 동작 데코레이터로 바로 전달된다는 것을 명심하기 바랍니다.

 

응답 상태 코드

경로 동작의 응답 내부에 사용하기 위한 (HTTP) status_code 를 정의할 수 있습니다.

 

404 처럼, int 를 바로 전달할 수 있습니다.

 

그러나 각각의 숫자 코드가 무엇에 관한 것인지 기억나지 않는다면, status 에 있는 손쉬운 상수를 사용할 수 있습니다:

 

 

이 상태 코드는 응답 내부에서 사용되며 OpenAPI 스키마에 추가됩니다.

 

기술적 세부사항

from starlette import status 를 사용할 수 있습니다.

FastAPI는 개발자의 편의성을 위해 starlette.status 와 동일한 fastapi.status 를 제공합니다. 그러나 이것은 Starlette으로부터 직접 전달 받습니다.

 

태그

(보통 단일 str 인) str 로 이루어진 list 와 함께 tags 매개변수를 전달하여, 경로 동작에 태그를 추가할 수 있습니다:

 

 

이것들은 OpenAPI 스키마에 추가되고 자동 문서 인터페이스에 의해 사용됩니다:

 

 

요약 및 설명

summary 및 description 을 추가할 수 있습니다:

 

 

독스트링을 통한 설명

설명은 보통 길고 여러 줄로 구성되어 있기 때문에, 함수의 독스트링에 경로 동작 설명을 선언하고 FastAPI은 그곳으로부터 설명을 읽을 수 있습니다.

 

마크다운을 독스트링에 작성할 수 있고, 이것은 (독스트링 들여쓰기를 고려하여) 올바르게 해석되고 표시됩니다.

 

 

이것은 대화형 문서에 사용됩니다:

 

 

응답 설명

매개변수 response_description 을 사용하여 응답 설명을 구체화할 수 있습니다:

 

 

정보

description 은 일반적인 경로 동작을 설명하고, response_description 은 응답을 구체적으로 설명한다는 걸 명심하시기 바랍니다.

 

확인

OpenAPI는 응답 설명을 요구하는 각 경로 동작을 구체화합니다.

따라서, 이것을 제공하지 않는다면, FastAPI는 "성공 응답" 중 하나를 자동으로 생성합니다.

 

 

경로 동작 지원 중단

만약 경로 동작의 지원이 중단되었다는 걸 표시하길 원하지만, 이를 삭제하지 않고 싶다면, 매개변수 deprecated 를 전달하기 바랍니다:

 

 

이것은 대화형 문서에서 명백하게 지원되지 않는 것으로 표시됩니다:

 

 

지원 되지 않는 것과 지원 되는 경로 동작이 어떻게 다른지 확인하기 바랍니다:

 

 

요약

경로 동작 데코레이터에 매개변수를 전달하여 경로 동작을 위한 메타데이터를 쉽게 구성 및 추가할 수 있습니다.

 

---

원문

https://fastapi.tiangolo.com/tutorial/path-operation-configuration/

Path Operation Configuration - FastAPI