Swagger API 명세를 만드는 두 가지 방법은 아래와 같습니다.
1. 서버 프로그래밍 언어를 거치지 않고 Swagger API를 독립적인 별도의 문서로 만드는 방식.
ex) yaml 파일을 생성하여 API를 명세.
2. 서버 프로그래밍 언어를 이용해서 Swagger API를 종속적인 형태로 만드는 방식.
ex) 스프링 프레임워크에서 어노테이션을 활용하여 API를 명세.

이번 포스팅에서는 1번 방법인 독립적인 별도의 문서로 만드는 방식으로 진행해보려 합니다.
API 명세를 쉽게 만들 수 있도록 해주는 SwaggerHub에서 샘플 데이터로 yaml 파일을 만들어본 뒤, 템플릿 없이도 만들어보도록 하겠습니다.

1. 연습용 API 명세서 작성

1) Create New API

Create New > Create New API를 눌러서 하나의 API 명세를 생성해 봅니다.
처음에는 아무것도 변경하지 않고, 이름만 지정하여서 생성해본다.

여기서는, Template: Petstore라는 기본 템플릿을 활용하는데
'애완동물마트'라는 주제로 만든 가상의 API 서비스들이 미리 들어있는 샘플 템플릿이라고 생각하면 된다.
CREATE API 버튼을 누르면 아래와 같이 기본적인 명세가 갖추어진 파일이 생성된다.
좌측에는 API의 정보가 있고, 가운데는 YAML 명세가 있다.
우측에는 API 명세에 대한 전체 내용이 있는데,
일반적으로 클라이언트 입장에서 보게 되는 API 문서가 바로 이것이다.

2) View Documentation 들어가보기

그림의 상단에 있는 View Documentation 아이콘을 누르면 (우측 항목인) 현재 작성된 API 명세의 Documentation만 나타난다.
이렇게 작성된 API 명세들은 Documentation에서 Execute라는 실제 서버로 전달할 수 있는 기능을 가지고 있다.
단지, Swagger API 명세로 작성된 문서만 가지고도 서버로 파라미터를 전달할 수 있는 테스트를 할 수 있다는 장점이 있다.

2. 실습용 API 명세서 작성

1) Create New API

이제, 템플릿을 사용하지 않고 처음부터 프로젝트를 만들면서 API를 추가하고 명세하기 위해
아래와 같이 Create New API를 진행하자.
(참고로, VERSION은 API 명세의 버전을 의미한다.)
아래와 같이 생성되었다면 정상이다.

2) yaml 파일 수정

먼저, 명세하려는 API를 정해야 하는데 여기서는 구글 검색을 사용할 때
검색창의 하단에 자동으로 노출되는 검색 자동완성 목록 API의 명세를 작성해보도록 한다.

검색 자동완성 목록 API의 Request URL은 아래와 같다.
www.google.com/complete/search?q={내용}&client=psy-ab
(※ client=psy-ab는 필수로 전달되어야 하는 파라미터로 보인다.)

위 API를 yaml 파일에 추가해보도록 하자.

(1) servers의 description, url 추가.

API Documentation에서는 간단히 API를 테스트 할 수 있는 기능을 제공하고 있는데,
이때, 명세서 yaml의 servers에 API를 테스트할 서버의 도메인을 적어줘야
해당 서버로 실제 리퀘스트를 전달하여 서버의 응답을 확인할 수 있다.

servers:
  - description: Google API
    url: https://www.google.com

(2) paths 추가.

paths에는 실제 API의 기능을 정의하는데 사용된다.
해당 API가 http method 중 어떤 것을 사용하며,
파라미터는 어떤 것을 사용하며,
응답은 어떤 형태로 처리할 것인지를 명시하는 것이 핵심이다.

paths:
  /complete/search:
    get:
      summary: 자동완성 검색 결과를 반환합니다.
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: client
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A Text File
          content:
            text/plain:
              schema:
                type: string

간단히 설명하자면,
/complete/search 란 경로에 접속했을 때에 대한 API를 명세하는데,
get 방식으로 들어간 경우, 파라미터로 전달된 2개의 string 값을 받아서 사용하도록 하였다.

여기서 in: query 방식은 쿼리스트링으로 넘어온 파라미터를 받을때 사용하며,
url path에 속하는 파라미터를 받을 때는 in: path를 사용한다.
(아래의 예시를 참고.)

# in: path를 사용하는 예시
paths:
  /todos/{id}:
    get:
      summary: exmample
      parameters:
        - name: id
          in: path
          required: true
          description: this is id
          schema:
            type: integer
      

이번 포스팅에서는 반환되는 응답코드가 '정상(200)' 케이스에 대해서만 고려하도록 하겠다.
응답코드 200을 반환하는 경우 자동완성이므로 텍스트 파일(text/plain)을 가지도록 하였고
그 텍스트 파일에 들어가는 내용의 타입은 문자라고 정의한다.

(3) 완성된 yaml 파일

openapi: 3.0.0
info:
  version: 1.0.0
  title: MY_TITLE
  description: 스웨거 실습 테스트
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/jwscript/SWAGGER_TEST/1.0.0
  - description: Google API
    url: https://www.google.com
paths:
  /complete/search:
    get:
      summary: 자동완성 검색 결과를 반환합니다.
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: client
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A Text File
          content:
            text/plain:
              schema:
                type: string

yaml 파일의 내용을 작성을 완료하였으면
상단의 Save를 클릭하고 View Documentation 아이콘을 누르고 테스트를 진행합니다.

(4) View Documentation에서 API 테스트 하기.

API documentation 에서 실제 구글 서버로 쿼리를 날린 결과 위와 같이 Code 200 으로 정상 응답이 받아졌음을 볼 수 있다.

Response Body의 파일을 다운로드 받아보면 아래와 같이 나오는데,
이는 구글 검색창에서 나오는 아래의 목록과 같다.
(직접 유니코드를 변경해보면 알 수 있다.)

기존에 개발되어 있는 API 소스를 RESTful API 호출로 변경하게 될 업무가 생길것 같아서
미리 Swagger에 대해 알아두는 중입니다.
Swagger API 명세를 작성하는 방법은 크게 두 가지가 있지만,
프로그래밍 언어에 독립적으로 yaml 파일로 구현하는 방법도 여러가지가 있는 것 같습니다.
이번 포스팅과 추후에 있을 포스팅에서 독립적으로 yaml 파일을 생성하는 여러가지 방법과 종속적으로 Swagger API 명세를 작성하는 방법 모두 써보도록 하겠습니다.

해당 글 작성에 참고한 링크

https://www.youtube.com/watch?v=akbdsrOpQ60&list=PLRx0vPvlEmdAezo0wkmUdT6WBCch0_1ie&index=2
https://www.youtube.com/watch?v=ARi-cXdIIj8&list=PLRx0vPvlEmdAezo0wkmUdT6WBCch0_1ie&index=2