🔴 문서 고도화란?

지금까지 api를 만들었는데 문서 화면을 보면 맘에 들지 않는 곳이 많고 실제로 api를 참고하는 개발자들이 보기 불편할 것 같다.

이렇게 api들이 분리가 되어 있지도 않고 무슨 API인지도 잘 모르겠다. 이제 내용을 함께 수정해보자.

🟠 문서 제목 및 설명 수정

from fastapi import FastAPI
from board import board_router
from todo.router import todo_router

app = FastAPI(
    title="concierge api",
    description="청약 api",
    version="0.0.1",
    docs_url="/api/docs",
    redoc_url="/api/redoc",
    openapi_url="/api/openapi.json"
)

app.include_router(board_router)
app.include_router(todo_router)

main.py 에 FastApi() 함수 내에 다음과 같이 내용들을 추가해주었다. 각 api들의 주소와 제목, 설명, 버전을 수정하는 설정이다.

이제 다음과 같이 제목과 설명 그리고 url이 수정되었다.

🟠 api를 tag별로 분리

제일 신경쓰이는 부분이였다.

todo_router = APIRouter(
    prefix="/api",
    tags=["todo"]
)

다음과 같이 APIRouter에 내용을 넣어주면 된다.

또한 api별로 tag를 달고 싶다면

@board_router.get(path="/board", tags=["board"])
def get() -> dict:
    return {"list" : board_list}

위와 같이 해주면 동일하게 된다. tags 안에는 배열 형태로 여러개를 묶어서 넣을 수도 있다.

그럼 다음과 같이 태그별로 api들이 묶이게 된다. 이정도만 해도 벌써 사용하기엔 무리가 없어 보인다!

이 외에도 msa 방식으로 서비스들이 분리가 되면 따로 api 문서 서버를 생성하여 swagger에서 반환되는 /openapi.json을 사용하여 문서를 통합하는 방법 등이 있지만 지금은 거기까진 알 필요 없다고 생각하고 이정도로 고도화를 끝낸다!