Swagger - Swagger Hub를 이용하는 법

swagger.io/

API Documentation & Design Tools for Teams | Swagger

gql은 자동으로 명세서를 만들어줘서 이런 작업이 필요 없습니다만, rest api 형식에서는 명세서를 수작업으로 만들어줘야 합니다. 프로젝트 규모가 작다면 코드를 훑어보는 정도로 되겠지만, 프로젝트 규모가 커질수록 명세서가 필요합니다.

클럽 하우스의 REST API End Point가 107개 라죠? (출처) 이걸 어떻게 다 기억합니까...

 

명세서 툴 중 오픈소스로 가장 많이 이용되는 게 Swagger 이기 때문에 한 번 이용해보고자 합니다.

자체 서버에서 스웨거 모듈을 이용하는 방법이 있고, 스웨거 허브를 이용하는 방법이 있습니다.

여기서는 스웨거 허브를 이용하는 방법을 살펴보겠습니다.

 

일단 스웨거 허브에 가입 후 새로운 api를 생성하도록 합시다.

 

 

api를 생성하면 다음과 같은yaml 코드를 볼 수 있습니다.

 

 

간단한 Get 엔드 포인트 문서화하기

 

GET jsonplaceholder.typicode.com/todos/1 명령을 보내면 다음과 같은 형태의 json을 반환하게 됩니다.

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

 

이를 문서화하면 다음과 같은 꼴로 나옵니다. 간단히 설명하자면,

server 에는 이용할 서버의 주소를, paths 에는 이용할 엔드포인트를 작성하면 됩니다. 

server에는 여러 개의 서버 주소를 넣을 수도 있습니다만, 프로젝트가 웬만큼 크지 않다면 이런 일은 없겠죠.

openapi: 3.0.0
info:
  version: 1.0.0
  title: api_example_title
  description: 아무거나 적습니다.
# 이용할 서버의 주소를 입력합니다.
servers:
  # 지우시면 안됩니다. 이 url이 있어야 저장 및 모킹을 만들어주기 때문입니다.
  - description: mocking server
    url: https://virtserver.swaggerhub.com/f852/api_example/1.0.0
  # jsonplaceholder를 이용할겁니다.
  - description: we will use jsonplaceholder
    url: https://jsonplaceholder.typicode.com
paths:
  /todos/{id}:
    get:
      summary: return todos by todo id
      parameters: 
        - name: id #파리미터 이름
          in: path # path내에 변수로 들어감
          required: true #반드시 필요한 파라미터임
          description: the id of todo
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content: 
            application/json:
              schema:
                type: object
                properties: 
                  userId:
                    type: integer
                  id:
                    type: integer
                  title:
                    type: string
                  completed:
                    type: boolean

 

결과적으론 아래와 같은 결과가 나옵니다.

 

 

 

해보시면 꽤나 번거로운 것을 알 수 있습니다.