소개

API 설계를 할 때의 환경 구축에 대한 조사한 내용입니다.

목적

환경 구축의 목적은 다음 두 가지입니다.

Swagger를 사용하여 API 사양을 작성 (설계)합니다.

작성한 API 스펙을 따라 응답을 리턴하는 모의 서버를 작성하십시오.

위의 목적을 바탕으로 Swagger-ui-watcher와 APISprout을 사용하여 환경을 만듭니다.
또, API 사양의 작성 방법으로서는 전용의 툴(Swagger-editor)을 이용하는 방법도 있습니다만, 이번은 로컬로 파일 작성을 실시하는 방법을 채용합니다.

Swagger-ui-watcher

Swagger-ui는 Swagger에서 정의한 API 사양을 브라우저에서 시각화하는 도구입니다.
Swagger-ui-watcher는 로컬에서 작성한 사양 파일의 표시에 특화한 것으로, 사양 파일의 변경시에 브라우저에 표시되는 Swagger-ui의 화면을 자동으로 갱신합니다. 로컬의 사양 파일의 수정을 실시하는 경우는 이쪽이 부드러운 조작이 가능합니다.

APISprout

APISprout은 Swagger를 사용하여 작성된 API 사양을 바탕으로 응답을 반환하는 모의 서버를 자동으로 구축하는 도구입니다.

환경 구축

Docker를 사용하여 환경을 구축하고 있습니다.

디렉토리 구성

.
├── docker-compose.yaml # Composeファイル
│
├── swagger
│   └── swagger.yaml # API仕様ファイル
│
└── swagger-ui-watcher
   └── build
       └── Dockerfile # swagger-ui-watcherのDockerファイル

docker-compose.yaml

version: '3'

services:
  swagger-ui-watcher:
    build: swagger-ui-watcher/build
    image: swagger-ui-watcher
    container_name: swagger-ui-watcher
    ports:
      - 8080:8000
    volumes:
      - ./swagger:/swagger
    command: /swagger/swagger.yaml

  apisprout:
    image: danielgtaylor/apisprout
    container_name: apisprout
    ports:
      - 8000:8000
    volumes:
      - ./swagger/swagger.yaml:/swagger.yaml
    command: /swagger.yaml --watch

Compose 파일은 swagger-ui-watcher와 apisprout 컨테이너를 정의합니다.
Swagger-ui-watcher는 공식 이미지( htps : // 후 b. 도 c r. 코 m / r / 쇼타 t / 슈게 r - 우이와 t 치 r / )가 아닌 Docker 파일에서 이미지를 생성합니다.
이것은 사양 파일명(swagger.yaml)을 외부에서 설정 가능하게 하기 때문입니다.

APISprout은 공식 이미지 ( htps // // 후 b. 두 c r. 이 m/r/다니에 lg한 yぉr/아피 sp 로우 t/ )를 바탕으로 컨테이너를 만들고 있습니다.
명령으로서 사양 파일명, watch 옵션을 지정하고 있습니다.
watch 옵션을 설정하면 swagger.yaml이 자동으로 로드됩니다.

Dockerfile (swagger-ui-watcher)

Swagger-ui-watcher 컨테이너의 Docker 파일은 다음과 같습니다.

FROM node:8-alpine

RUN npm install swagger-ui-watcher -g

ENTRYPOINT ["swagger-ui-watcher", "--no-open", "--host", "0.0.0.0"]

VOLUME ["/swagger"]

EXPOSE 8000

swagger.yaml

공식 예에 있는 swagger.yaml을 수정한 것을 이용해 동작 확인을 실시합니다.
htps : // 슈게 r. 이오 / 도 cs / s 페시 후 카치 온 / 바시 c st 루 c 얽힌 /

아래에서는 테스트용 서버의 URL을 모의 서버의 URL로 변경하고 있습니다.

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://localhost:8000
    description: Optional server description, e.g. Internal staging server for testing
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

동작 확인

다음 명령을 사용하여 docker 컨테이너를 시작하고 http://localhost:8080 에 액세스합니다.

docker-compose up -d

아래와 같은 화면이 표시되므로 서버를 풀다운에서 선택하고 API를 클릭하고 "Try it out"⇒ "Execute"를 선택하여 모의 서버 API를 실행할 수 있습니다.