첫걸음

첫걸음

2021. 9. 25. 15:44ㆍ[개발] 문서 번역/FastAPI

가장 단순한 FastAPI 파일은 다음과 같습니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

위 코드를 [main.py](http://main.py) 에 복사하고, 라이브 서버를 실행합니다.

$ uvicorn main:app --reload

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.

참고
- main : 파일 [main.py](http://main.py) (파이썬 "모듈").
- app : [main.py](http://main.py) 내부의 app = FastAPI() 줄에서 생성한 오브젝트.
- --reload : 코드 변경 후 서버 재시작. 개발에만 사용
uvicorn main:app 명령은 다음을 의미합니다:

출력에 아래와 같은 줄이 있습니다:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

해당 줄은 로컬에서 앱이 서비스되는 URL을 보여줍니다.

확인하기

브라우저로 http://127.0.0.1:8000 를 여세요.

아래와 같은 JSON 응답을 볼 수 있습니다:

{"message":"Hello World"}

대화형 API 문서

이제 http://127.0.0.1:8000/docs 로 가봅니다.

자동 대화형 API 문서를 볼 수 있습니다.

대안 API 문서

그리고 이제, http://127.0.0.1:8000/redoc 으로 가봅니다.

대안 자동 문서를 볼 수 있습니다.

OpenAPI

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

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

API "스키마"

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

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

데이터 "스키마"

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

이러한 경우 JSON 속성, 가지고 있는 데이터 타입 등을 뜻합니다.

OpenAPI와 JSON 스키마

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

가공되지 않은 OpenAPI 스키마가 어떻게 생겼는지 궁금하다면, http://127.0.0.1:8000/openapi.json 여기에서 직접 볼 수 있습니다.

{
   "openapi":"3.0.2",
   "info":{
      "title":"FastAPI",
      "version":"0.1.0"
   },
   "paths":{
      "/":{
         "get":{
            "summary":"Root",
            "operationId":"root__get",
            "responses":{
               "200":{
                  "description":"Successful Response",
                  "content":{
                     "application/json":{
                        "schema":{

                        }
                     }
                  }
               }
            }
         }
      }
   }
}

단계별 요약 (Step by Step)

Step 1 : FastAPI 임포트

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

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

기술 세부사항FastAPI 로 Starlette의 모든 기능을 사용할 수 있습니다.
FastAPI 는 Starlette 를 직접 상속하는 클래스입니다.

Step 2 : FastAPI "인스턴스" 생성

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

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

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

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

$ uvicorn main:app --reload

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

아래처럼 앱을 만든다면:

from fastapi import FastAPI

my_awesome_api = FastAPI()

@my_awesome_api.get("/")
async def root():
    return {"message": "Hello World"}

이를 [main.py](http://main.py) 파일에 넣고, uvicorn을 아래처럼 호출해야 합니다:

$ uvicorn main:my_awesome_api --reload

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Step3 : Path Operation 생성

경로(Path)

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

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

https://example.com/items/foo

...경로는 다음과 같습니다:

/items/foo

정보
"경로(Path)"는 일반적으로 "endpoint" 또는 "route"라고도 불립니다.

동작

여기서 "동작(Operation)"은 HTTP "메소드" 중 하나를 나타냅니다.

다음 중 하나이며:

POST
GET
PUT
DELETE

... 다음과 같이 일반적이지 않은 것들도 있습니다.

OPTIONS
HEAD
PATCH
TRACE

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

API를 빌드하는 동안 일반적으로 특정 행동을 수행하기 위해 특정 HTTP 메소드를 사용합니다.

일반적으로 다음을 사용합니다:

POST : 데이터를 생성하기 위해.
GET : 데이터를 읽기 위해.
PUT : 데이터를 업데이트 하기 위해.
DELETE : 데이터를 삭제하기 위해.

그래서 OpenAPI에서는 각 HTTP 메소드들을 "동작(Operation)"이라 부릅니다.

이제부터 우리는 메소드를 "동작(Operation)" 이라고도 부를겁니다.

경로 동작(Path Operation) 데코레이터 정의

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

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

경로 /
get 동작 사용
@decorator 정보함수 맨 위에 놓습니다.우리의 경우, 이 데코레이터는 FastAPI 에게 아래 함수가 경로 / 에 해당하는 get 동작을 하라고 알려줍니다.
이것이 "경로 동작 데코레이터" 입니다.
"데코레이터" 아래 있는 함수를 받고 그걸 이용해 무언가를 합니다.
이 @something 문법은 파이썬에서 "데코레이터"라 부릅니다.

다른 동작도 쓸 수 있습니다:

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

일반적이지 않은 것들도 있습니다:

app.options()
app.head()
app.patch()
app.trace()
팁FastAPI는 특정 의미를 강제하지 않습니다.예를 들어 GraphQL을 사용할 때 일반적으로 POST 동작만 사용하여 모든 행동을 수행합니다.
여기서 정보는 지침서일뿐 요구사항이 아닙니다.
각 동작(HTTP 메소드)을 원하는 대로 사용해도 됩니다.

Step 4 : 경로 동작 함수 정의

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

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

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

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

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

위의 경우 async 함수입니다.

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

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"message": "Hello World"}

Note
차이점을 모르겠다면 Async: "In a hurry?" 를 확인하세요(번역예정).

Step 5 : 콘텐츠 반환

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

dict, list, 단일값을 가진 str, int 등을 반환할 수 있습니다.

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

JSON으로 자동 변환되는 객체들과 모델들이 많이 있습니다(ORM 등을 포함). 가장 마음에 드는 것을 사용하세요, 이미 지원되고 있을 겁니다.

요약

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

'[개발] 문서 번역 > FastAPI' 카테고리의 다른 글

도입부 (0)	2021.09.25

도입부 2021.09.25

Lithium Flower