[ FastAPI ] 첫 단계

가장 간단한 FastAPI 파일은 다음과 같은 형태입니다:

 

 

main.py 파일에 이 코드를 복사하시기 바랍니다.

 

그리고 라이브 서버를 실행하시기 바랍니다:

 

 

참고
uvicorn main:app 명령어 의미는 다음과 같습니다.

- main : (파이썬 "모듈"인) main.py 파일
- app : main.py 파일에 app = FastAPI() 라인으로 만들어진 객체
- --reload : 코드가 변경될 때의 서버 자동 재시작. 개발 환경에서만 사용.

 

결과물에는, 다음과 같은 라인이 출력됩니다:

 

 

이 라인은 당신의 로컬 기계에서, 애플리케이션이 제공되는 URL을 보여줍니다.

 

결과 확인

http://127.0.0.1:8000 주소로 브라우저를 열어보시기 바랍니다.

 

다음과 같은 JSON 응답을 확인할 수 있습니다:

 

 

대화형 API 문서

이제 http://127.0.0.1:8000/docs 주소로 이동하시기 바랍니다.

 

(Swagger UI에서 제공한) 자동 대화형 API 문서를 확인할 수 있습니다.

 

 

대체 API 문서

그리고 이제 http://127.0.0.1:8000/redoc 으로 이동하시기 바랍니다.

 

(ReDoc에서 제공한) 자동 대체 API 문서를 확인할 수 있습니다.

 

OpenAPI

FastAPI는 API 정의를 위한 OpenAPI 표준을 사용하여 모든 API의 "스키마"를 생성합니다.

 

"스키마"

"스키마"는 무언가에 대한 정의 또는 설명입니다. 이를 구현하는 코드가 아니라 추상적인 설명일 뿐입니다.

 

API "스키마"

이 경우, OpenAPI는 API의 스키마를 어떻게 정의하는지 지시하는 규격입니다.

 

이 스키마 정의는 API 경로, 가능한 매개변수, 기타 등등을 포함합니다.

 

데이터 "스키마"

"스키마"라는 용어는 JSON 내용처럼,  어떤 데이터의 형태를 나타낼 수도 있습니다.

 

이러한 경우, JSON 어트리뷰트, 그리고 가지고 있는 데이터 자료형, 기타 등등을 의미합니다.

 

OpenAPI와 JSON 스키마

OpenAPI는 API에 대한 API 스키마를 정의합니다. 또한 이 스키마에는 JSON 데이터 스키마의 표준인, JSON 스키마를 사용하여 API를 통해 보내고 받은 데이터에 대한 정의 (또는 "스키마") 를 포함합니다.

 

openapi.json 확인

가공되지 않은 OpenAPI 스키마가 어떻게 생겼는지 궁금하다면, FastAPI는 자동으로 모든 API의 설명과 함께 JSON (스키마) 을 생성합니다.

 

여기에서 직접 확인할 수 있습니다: http://127.0.0.1:8000/openapi.json.

 

다음과 같이 시작하는 JSON을 확인할 수 있습니다:

 

 

OpenAPI의 용도

OpenAPI 스키마는 포함된 두 개의 대화형 문서 시스템을 작동시킵니다.

 

그리고 OpenAPI의 모든 것을 기반으로 하는, 수십 가지 대안이 있습니다. FastAPI로 빌드된 애플리케이션에 이러한 대안을 쉽게 추가 할 수 있습니다.

 

API와 통신하는 클라이언트를 위해, 코드를 자동으로 생성하는 데 사용할 수도 있습니다. 예를 들어, 프론트엔드, 모바일, IoT 애플리케이션이 있습니다.

 

 

단계별 요약

1단계: FastAPI 임포트

 

FastAPI 는 API에 대한 모든 기능을 제공하는 파이썬 클래스입니다.

 

기술 세부사항
FastAPI 는 Starlette 를 직접 상속하는 클래스입니다.

FastAPI 로도 Starlette의 모든 기능을 사용할 수 있습니다.

 

2단계: FastAPI "인스턴스" 생성

 

여기 작성된 app 변수는 FastAPI 클래스의 "인스턴스"가 됩니다.

 

이것은 모든 API를 생성하기 위한 상호작용의 주요 지점이 될 것입니다.

 

이 app 은 다음 명령어에서 uvicorn 이 참조하고 있는 것과 동일합니다:

 

 

 

만약 app을 아래 처럼 만든다면:

 

 

이를 main.py 파일에 넣고, uvicorn 을 다음과 같이 실행해야 합니다:

 

 

3단계: 경로 동작 생성

경로

여기서 "경로"는 첫 번째 / 에서 시작하는 URL의 마지막 부분을 의미합니다.

 

그러므로, 아래와 같은 URL에서:

 

 

경로는 다음과 같습니다:

 

 

정보
"경로"는 또한 일반적으로 "엔드포인트" 또는 "라우트"라고 불립니다.

 

API를 빌드하는 동안, "경로"는 "고려 사항"과 "리소스"를 분리하는 주요 방법입니다.

 

동작

여기서 "동작"은 HTTP "메서드" 중 하나를 의미합니다:

 

다음 중 하나이며:

 

• POST
• GET
• PUT
• DELETE

 

... 더 낯선 것도 있습니다:

 

• OPTIONS
• HEAD
• PATCH
• TRACE

 

HTTP 프로토콜에서는, 이러한 "메서드"를 하나 (또는 그 이상) 사용하여 각 경로와 통신할 수 있습니다.

 

---

 

API를 빌드할 때, 보통 특정 행동을 수행하기 위해 특정 HTTP 메서드를 사용합니다.

 

보통 다음과 같이 사용합니다:

 

• POST : 데이터 생성.
• GET : 데이터 조회.
• PUT : 데이터 수정.
• DELETE : 데이터 삭제.

 

그래서, OpenAPI에서는, 각 HTTP 메서드를 "동작"이라 부릅니다.

 

이제부터 우리도 메서드를 "동작"이라고도 부를 것입니다.

 

경로 동작 데코레이터 정의

 

@app.get("/") 은 FastAPI에게 바로 아래있는 함수가 다음으로 이동하는 요청을 처리한다는 것을 알려줍니다:

 

• 경로 /
• get 동작 사용

 

@decorator 정보
이 @something 문법은 파이썬에서 "데코레이터"라 부릅니다.

마치 예쁜 장식용 모자처럼 (개인적으로 이 용어가 여기서 유래한 거 같습니다) 함수 위에 작성합니다.

"데코레이터"는 본인 아래 있는 함수를 받고 그걸 이용해 무언가 실행 합니다.

우리의 경우, 이 데코레이터는 FastAPI에게 아래 함수가 경로 / 에 해당하는 get 동작을 사용해야 한다고 알려줍니다.

이것이 "경로 동작 데코레이터"입니다.

 

 

물론 다른 동작도 사용할 수 있습니다:

 

• @app.post()
• @app.put()
• @app.delete()

 

물론 더 낯선 동작도 사용 가능합니다:

 

• @app.options()
• @app.head()
• @app.patch()
• @app.trace()

 

팁
각 동작 (HTTP 메서드) 을 원하는 대로 자유롭게 사용해도 됩니다.

FastAPI는 특정 의미를 강제하지 않습니다.

여기 작성된 정보는 지침일 뿐, 요구사항이 아닙니다.

예를 들어, GraphQL을 사용할 때 일반적으로 POST 동작만 사용하여 모든 행동을 수행합니다.

 

4단계: 경로 동작 함수 정의

다음은 우리의 "경로 동작 함수"입니다:

 

• 경로: 경로는 / 입니다.
• 동작: 동작은 get 입니다.
• 함수: 함수는 "데코레이터" 아래에 있는 함수 ( @app.get("/") 아래) 입니다.

 

이것은 파이썬 함수입니다.

 

GET 동작을 사용하여 URL " / "에 대한 요청을 받을 때마다 FastAPI에 의해 호출됩니다.

 

이 경우, async 함수입니다.

 

---

 

async def 대신 일반 함수로 정의할 수 있습니다.

 

 

노트
차이점을 모르겠다면, Async: "빠르게 훑어 보기" 을 확인하시기 바랍니다.

 

5단계: 콘텐츠 반환

 

dict , list , 특이한 값으로 str , int 등을 반환할 수 있습니다.

 

Pydantic 모델을 반환할 수도 있습니다 (더 자세한 내용은 나중에 살펴봅니다).

 

(ORM, 기타 등등을 포함해) JSON으로 자동 변환되는 객체와 모델이 많이 있습니다.

 

가장 마음에 드는 것을 사용하시기 바랍니다, 이미 지원되고 있을 가능성이 높습니다.

 

요약

• FastAPI 임포트.
• app 인스턴스 생성.
• ( @app.get("/") 처럼) 경로 동작 데코레이터 작성.
• (위에 있는 def root(): ... 처럼) 경로 동작 함수 작성.
• ( uvicorn main:app --reload 처럼) 개발 서버 실행.

 

---

원문

https://fastapi.tiangolo.com/tutorial/first-steps/

First Steps - FastAPI