Etc

Swagger 사용법 - Swagger 로 API 명세서 만들기 (기본)

앤오엔 2022. 4. 20. 00:43

협업하는 프로젝트에서 API 명세서는 단연코 가장 중요한 문서라고 할 수 있다.

효율적이고 효과적인 커뮤니케이션을 하기 위해선 API 문서가 꼭 필요하다.

 

예를 들어 프론트엔드가 브라우저의 요청을 담아 백엔드 서버로 데이터를 전달해야 하는 상황이라고 할 때,

잘 정리된 API 문서가 있으면 빠르고 쉽게 코드를 작성할 수 있어 불필요한 커뮤니케이션 리소스를 줄일 수 있다.

또, 과거 진행했던 프로젝트의 코드를 해석하고 관리하는 데도 도움이 된다.

 

전에 API 테스트 및 문서 작성하는 프로그램으로 Postman을 사용했었는데,

이번에는 Swagger을 알게 되어 테스트차 API 명세서을 작성해보았다.

 

 

 

 

Swagger 소개

API 문서를 자동으로 시각화해주는 툴로,

파라미터가 포함된 URI 주소 등의 내용을 빠르게 표준화된 문서로 관리할 수 있다.

https://swagger.io/

 

API Documentation & Design Tools for Teams | Swagger

 

swagger.io

 

장점

1) Swagger openAPI는 코드 추가 없이 OpenAPI 규격에 맞게 API 정보를 실시간으로 업데이트한다.
2) RESTFul표준 방식의 API관리 뿐만 아니라 샘플 데이터와 호출 테스트를 제공한다.

   암호만 알면 서버에 API 테스트 패킷을 보내 API가 잘 동작하는지 확인할 수 있다.

 

Swagger Definition 구성 요소

Swagger에서 API를 처음 생성할 때 기본 코드가 자동으로 만들어지는데, YAML* 문법을 채택하고 있다.

(* YAML 문법에 대해서는 뒤어 이어 자세하게 설명할 예정)

 

Swagger 구성요소는 다음과 같다.

 

ㆍopenapi : 사용하는 Open API의 버전

ㆍinfo: (Optional) API에 필요한 정보

   - title: API 제목

   - version: API 버전

   - description: API 상세정보

ㆍservers: API에 대한 기본 URL을 정의

ㆍapis: containing annotations 을 포함하는 모든 파일

openapi: 3.0.0
info:
  version: 1.0.0
  title: TestAPI
  description: Swagger Test API
paths: {}
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/<Owner>/<Title>/<openapiVersion>

 

 

YAML*

YAML은 구성 파일 작성에 자주 사용되는 데이터 직렬화 언어로 원래 "또 다른 마크업 언어 (Yet Another Markup Language)" 라는 뜻이었다고 한다.

그러나 문서용보다는 데이터용으로 더 많이 쓰이면서 "YAML은 마크업 언어가 아니다(YAML ain’t markup language)" 라는 재귀 약어를 가지게 되었다.

 

YAML는 JSON의 상위 집합이라 YAML에서도 JSON 파일을 사용할 수 있다.

가장 큰 특징으로는, 괄호나 따옴표 등이 없고 Python 처럼 띄어쓰기로 구문을 나누며 주석도 # 으로 표기한다.

여기서 주의해야 할 점은 주석도 띄어쓰기로 잘 나누어서 작성해야 한다.

 

리스트 : block 형태는 - 로, inline 형태는 [](대괄호)로 표현

 # block format
 - apple
 - banana
 # inline format
 [apple, banana]

해쉬 : JSON 과 비슷한 key: value 로 표현

 # Block
 name: Hanna
 age: 40
 # Inline
 {name: Hanna, age: 40}

 

 

Swagger로 API 명세서 작성하기

가상 서버 MyJSONSERVER 로 Swagger를 어떻게 사용하는지 알아보기로 했다.

우선, 테스트할 API로 2가지를 선택했다.

 

1) GET /demo/posts

URL: https://my-json-server.typicode.com/typicode/demo/posts

[
  {
    "id": 1,
    "title": "Post 1"
  },
  {
    "id": 2,
    "title": "Post 2"
  },
  {
    "id": 3,
    "title": "Post 3"
  }
]

2) GET /demo/posts/:id

URL: https://my-json-server.typicode.com/typicode/demo/posts/:id

{
    "id": 1,
    "title": "Post 1"
}

 

 

 

회원가입 및 API 생성

1. https://app.swaggerhub.com/home 페이지 접속

 

 

2. 회원가입 → 로그인: Github로 로그인 가능

 

 

3. 좌측 메뉴의 [create new] 클릭 → 아래처럼 항목 기입 → Create API 클릭

 

  - OpenAPI Version : 최신 버전인 3.0.0 선택

  - Template : 굳이 써야할 이유가 없다면 None 선택

  - Name : 생성한 API의 이름

  - Version : 최초 생성이라면 1.0.0 으로 기입

  - Title: Name과 같게 하는 것이 편의상 좋음

  - Description : API 설명

  - Owner : 가입할 때 작성한 닉네임이 표시됨

 

 

 

4. 자동으로 생성된 API의 코드를 수정하고 [save]로 변경 사항 저장 

 

 

5. 위에서 선택한 1), 2) API 출력 결과에 맞게 Swagger API 코드를 수정

기본 코드
openapi: 3.0.0
info:
  version: 1.0.0
  title: TestAPI
  description: Swagger Test API
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/<Owner>/<Title>/<Version>

 

 5-1. [server] 키에 테스트할 URL값 추가한다.

servers:
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/<Owner>/<Title>/<Version>
  # Added by API MYJSONSERVER
  - description: JSON Placeholder my-json-server API
    url: https://my-json-server.typicode.com/typicode

5.2. 각 API와 관련된 정보를 입력한다. 이 때, 각 값의 자료형도 지정해준다.

paths: 
	# GET /demo/posts
	/demo/posts: 
    get: 
      summary: Returns all posts
      responses:
          '200' : 
            description: OK
            content:
              application/json:
                schema:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                      title:
                        type: string
    # GET /demo/posts/:id
    /demo/posts/{id}: 
    get: 
      summary: Returns posts by ID
      parameters: 
        - name: id
          in: path
          required: true 
          description: The ID of the posts to return 
          schema:
            type: integer
      responses:
          '200' : 
            description: OK
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string

 

 

6. 코드를 다 작성했다면 우측의 [View Documentation] 아이콘을 클릭한다.

 

 

7. Documentation 에 반영된 api 명세를 확인한다.

코드가 실시간으로 수정되지 않으니 Documentation 에서 변경사항을 반영하려면 새로고침을 꼭 해야 한다.

 

 

8. [Try it out] 버튼과 [Execute] 버튼으로 API 테스트를 진행한다.

 

 

 

 

 

 

개인적으로 생각하는 Postman 과 Swagger 비교
- Postman이 Swagger보다 조금 더 무겁고 느린 느낌이며, 노가다성 작업이 꽤 있었다.
- Swagger를 아직 충분히 써보지는 않았지만, YAML 이라는 허들(?)만 넘으면 빠르게 쓸 수 있을 것 같다.

 

 

 

▼ 더 나아가기

Swagger 사용법 - Node.js + Express.js 환경에서 Swagger API 설정하기 (심화)

 

 

 

 

참고

- YAML

https://ko.wikipedia.org/wiki/YAML

https://www.redhat.com/ko/topics/automation/what-is-yaml

 

 

저작자표시 비영리 변경금지 (새창열림)