[ FastAPI ] 경로 매개변수

파이썬 문자열 포맷팅에서 사용되는 문법으로 똑같이 경로 "매개변수" 또는 "변수"를 선언할 수 있습니다:

 

 

경로 매개변수의 값 item_id 는 item_id 인자로 함수에 전달됩니다.

 

따라서, 만약 이 예시를 실행하고 http://127.0.0.1:8000/items/foo로 이동한다면, 다음과 같은 결과를 확인할 수 있습니다:

 

 

자료형을 사용한 경로 매개변수

표준 파이썬 자료형 어노테이션을 사용하여, 함수 속 경로 매개변수의 자료형을 정의할 수 있습니다:

 

 

이 경우, item_id 는 int 로 선언 되었습니다.

 

확인
이것은 함수 내부에서의, 에러 확인, 자동 완성, 기타 등등의 편집기 도움을 지원합니다.

 

데이터 변환

만약 이 예시를 실행하고 http://127.0.0.1:8000/items/3로 브라우저를 연다면, 다음과 같은 결과를 확인할 수 있습니다:

 

 

확인
문자열 "3" 이 아닌, 파이썬 int , 3 으로 함수가 값을 받은 것을 (그리고 반환한 것을) 잊지마시기 바랍니다.

따라서, 이러한 자료형 선언을 통해, FastAPI는 자동으로 요청을 "파싱"해서 제공합니다.

 

데이터 유효성 검사

그러나 만약 http://127.0.0.1:8000/items/foo로 브라우저를 이동한다면, 다음과 같이 정교한 HTTP 오류를 확인할 수 있습니다:

 

 

왜냐하면 경로 매개변수 item_id 의 값으로 int 가 아닌, "foo" 가 들어왔기 때문입니다.

 

만약 다음과 같이 int 대신 float 을 전달할 경우 똑같은 오류가 발생합니다: http://127.0.0.1:8000/items/4.2

 

확인
따라서, 파이썬의 자료형 선언과 동일한 방법으로, FastAPI 또한 데이터 유효성 검사를 제공합니다.

정확히 어떤 부분에서 유효성 검사를 통과하지 못해 오류가 발생했는지 명백하게 알려준다는 걸 잊지마시기 바랍니다.

이것은 API와 상호작용하는 개발과 코드 디버깅 단계에서 도움이 많이 될 것입니다.

 

문서

그리고 http://127.0.0.1:8000/docs로 브라우저를 연다면, 자동, 대화형, API 문서를 다음과 같이 확인할 수 있습니다:

 

 

확인
다시 한 번, 파이썬의 자료형 선언과 동일한 방법으로, FastAPI 또한 (Swagger UI 통합) 자동, 대화형 문서를 제공합니다.

경로 매개변수가 정수형으로 선언된 것을 잊지마시기 바랍니다.

 

표준-기반 이점을 가진, 대체 문서

그리고 스키마가 OpenAPI 표준으로 생성되었기 때문에, 이와 호환 가능한 도구가 많습니다.

 

이것 덕분에, FastAPI는 자체적으로 (ReDoc을 사용하여) http://127.0.0.1:8000/redoc로 접근 가능한, 대체 API 문서를 제공합니다.

 

 

동일한 방법으로, 다양한 언어를 위한 코드 생성 도구를 포함하여, 호환 가능한 도구가 많이 있습니다.

 

Pydantic

모든 검증은 Pydantic에 의해 내부적으로 수행되기 때문에, 이것이 제공하는 모든 이점을 취할 수 있습니다. 전문가에게 맡겨진 것이니 걱정하지 마시기 바랍니다.

 

str , float , bool 과 같은 동일한 자료형 선언은 물론 다양한 복합 데이터 자료형도 사용 가능합니다.

 

튜토리얼의 다음 챕터에서 이에 관해 더 자세히 살펴볼 것입니다.

 

순서 문제

경로 동작을 만들 때, 고정된 경로가 있는 상황을 겪을 수 있습니다.

 

예를 들어 /users/me 처럼, 현재 사용자 데이터를 가져오는 경우를 살펴 봅시다.

 

특정 사용자 ID를 통해 해당 사용자 데이터를 가져오는 /users/{user_id} 와 같은 경로도 함께 작성되었을 수 있습니다.

 

이때 경로 동작는 순서 대로 평가되기 때문에, /users/me 라는 경로가 /users/{user_id} 보다 반드시 먼저 선언되어야 합니다:

 

 

그렇게 하지 않는다면, /users/{user_id} 경로는 값으로 "me" 를 가진 매개변수 user_id 를 전달 받은 것으로 "판단"하여, /users/me 와 매치됩니다.

 

미리 정의된 값

만약 경로 매개변수를 받는 경로 동작을 만들었지만, 가능한 유효한 경로 매개변수 값이 미리 정의되길 원한다면, 표준 파이썬의 Enum 을 사용할 수 있습니다.

 

Enum 클래스 생성

Enum 을 임포트하고 str 과 Enum 을 상속 받는 서브-클래스를 만듭니다.

 

str 을 상속 받음으로써 API 문서는 값이 무조건 string 이어야 하고 올바르게 렌더링할 수 있다는 걸 알게 됩니다.

 

이제 아래와 같이 사용 가능한 유효한 값이 될, 고정된 값과 함께 클래스 어트리뷰트를 만듭니다:

 

 

정보
열거형 (또는 enums) 는 파이썬 버전 3.4 이후로 사용 가능합니다.

 

팁
"AlexNet", "ResNet", 그리고 "LeNet"은 단지 머신 러닝 모델의 이름일 뿐입니다.

 

경로 매개변수 선언

( ModelName 이란 이름으로) 위에서 만든 enum 클래스를 사용하여 자료형 어노테이션과 함께 경로 매개변수를 만듭니다:

 

 

문서 확인

경로 매개변수로 사용 가능한값이 미리 정의 되었기 때문에, 아래와 같이 멋진 대화형 문서를 확인할 수 있습니다:

 

 

파이썬 열거형을 활용한 작업

경로 매개변수의 값은 열거형 멤버가 됩니다.

 

열거형 멤버 비교

ModelName 이라는 이름으로 만든 enum에서 열거형 멤버를 비교할 수 있습니다.

 

 

열거형 값 얻기

model_name.value 을 사용하여, 또는 일반적으로, your_enum_member.value 을 사용하여 실제 값 (이 경우 str ) 을 얻을 수 있습니다:

 

 

팁
ModelName.lenet.value 를 통해 "lenet" 값에 접근할 수도 있습니다.

 

열거형 멤버 반환

( dict 과 같은) 중첩된 JSON 바디나, 경로 동작으로 부터 열거형 멤버를 반환 받을 수 있습니다.

 

클라이언트에 반환되기 전 각각 해당하는 값 (이 경우 문자열) 으로 변환됩니다:

 

 

클라이언트에서 다음과 같은 JSON 응답을 받습니다:

 

 

경로를 포함한 경로 매개변수

/files/{file_path} 라는 경로를 가진 경로 동작이 있다고 가정해봅시다.

 

그런데 home/ubuntu/myfile.txt 와 같이, 스스로 경로를 포함하고 있는 file_path 가 필요합니다.

 

이때, 해당 파일에 관한 URL은 다음과 같습니다: /files/home/johndoe/myfile.txt .

 

OpenAPI 지원

OpenAPI는 테스트와 정의가 어려운 상황으로 이어질 수 있는, 경로를 포함한 경로 매개변수을 선언하는 방법을 지원하지 않습니다.

 

그럼에도 불구하고, Starlette의 내부 기능 중 하나를 사용해, FastAPI에서 구현 가능합니다.

 

그리고 매개변수가 경로를 포함해야 한다는 걸 문서에 알리지 않아도, 문서는 여전히 동작할 것입니다.

 

경로 변환

Starlette에서 제공하는 옵션을 사용하여, 다음과 같은 URL을 사용하는 경로가 포함된 경로 매개변수를 선언할 수 있습니다:

 

 

이 경우, 매개변수의 이름은 file_path 가 되고, 마지막 부분인, :path 는 매개변수가 어떤 경로와 매치되어야 한다는 걸 말해줍니다.

 

따라서, 다음과 같이 사용할 수 있습니다:

 

 

팁
선행 슬래시( / )와 함께, /home/johndoe/myfile.txt 를 포함하는 매개변수가 필요할 수 있습니다.

이런 경우, URL은 다음과 같습니다: files 와 home 사이에 더블 슬래시( // )를 사용한, /files//home/johndoe/myfile.txt

 

요약

FastAPI를 통해, 단순하고, 직관적이며 표준 파이썬 자료형 선언을 사용하여, 다음과 같은 기능을 수행할 수 있습니다:

 

• 에디터 지원: 에러 확인, 자동 완성, 기타 등등.
• 데이터 "파싱"
• 데이터 유효성 감사
• API 어노테이션과 자동 문서

 

그리고 이 모든 걸 단지 한 번만 선언하면 됩니다.

 

이것이 아마 (근본적인 성능을 제외하고) 다른 대안적인 프레임워크와 비교했을 때 FastAPI를 통해 얻을 수 있는 주요한 가시적인 장점일 것입니다.

 

---

원문

https://fastapi.tiangolo.com/tutorial/path-params/

Path Parameters - FastAPI