swagger とか openapi の概要をサッと知るための記事

# 概要
swagger って調べてみたら openapi とか出てきたんだけどみたいな人のための記事です。
やってることはわりと単純なことなので、図解してみればわかりやすいかと思います。

# openapi ってなに？
API 定義書の書き方を仕様として定めましょう、っていう流れから生まれたもの。
https://github.com/OAI/OpenAPI-Specification

API 定義ってざっくり言ってますが、公式にも書いてある通り REST API に対応するものです。
>The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. 

## swagger ってなによ？
openapi の仕様を書いたり見たりするのに便利なツール群についてる名前。
swagger で使ってた書き方とかが基準になって openapi が策定された、みたいなイメージ。
昔 swagger って呼ばれてたらしーぜ、ってくらいの認識で。

# エクセルから yaml へ
swagger-ui とか swagger-editor とか調べると色々出てきますが至極単純化すると↓みたいな。

![openapi.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/a1e9e7f5-6cd7-05a2-7764-675f7cfd94c9.png)

つまり、このエクセルが
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/3c12589d-bd1d-332b-368b-04cb606dbb6a.png)

↓

こんな感じの yaml に

```yaml:openapi-sample.yml
openapi: "3.0.0"
info:
  version: 1.0.0
  title: sample api
  description: sample api definition.
  contact:
    name: sample team
    email: sample@sample.com
    url: https://sample.com/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: http://localhost:4011
    description: local mock server. https://github.com/stoplightio/prism
paths:
  /user/{id}:
    get:
      tags:
        - user
      parameters:
        - name: id
          in: path
          description: use information api
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: user information response
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/user'
components:
  schemas: 
    user: 
      type: object 
      required: 
        - user_id
      properties:
        user_id: 
          type: integer
          format: int64
          example: 123456
        name:
          type: string
          example: testuser
tags:
  - name: user
    description: ユーザーに関する API
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/b5d57e31-fa21-90c2-7e2f-efd6078a7ecf.png)

正確に言うと yaml じゃなくて json でもよいです。

## ただエクセルのほうが見やすくねぇ？
ただ yaml だとパッと見わかりづらい & 直す場所探しづらいので、これを便利にするためのツールがあります。
これが swagger-ui (見やすくする), swagger-editor (直しやすくする)といったものたちです。他にもそれっぽいツールはいくつもあると思います。

![openapi-editor-ui.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/ae3666ed-0ce9-a5ca-6bb9-413f98c626ad.png)

[swagger-editor](https://swagger.io/tools/swagger-editor/)
[swagger-editor github](https://github.com/swagger-api/swagger-editor)
[swagger-ui](https://swagger.io/tools/swagger-ui/)
[swagger-ui github](https://github.com/swagger-api/swagger-ui)

# docker で実際に動かす
下記ファイル内にある swagger-server については後述。

```yaml:openapi-docker-compose.yml

version: "3.7"
services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    environment:
      - SWAGGER_JSON=/openapi-sample.yml #読み込む yaml ファイルを指定
    ports:
      - "88:8080"
    volumes:
      - ./openapi-sample.yml:/openapi-sample.yml #読み込む yaml ファイルをコンテナに送っておく
    networks:
      - openapi

  swagger-server:
    image: stoplight/prism:3
    ports:
      - "4011:4010"
    command: mock -h 0.0.0.0 /openapi-sample.yml
    volumes:
      - ./openapi-sample.yml:/openapi-sample.yml
    networks:
      - openapi

networks:
  openapi:

```

以下のコマンドでコンテナを立ち上げます。

```bash
docker-compose -f openapi-docker-compose.yml up -d
```

`localhost:88` で openapi-sample.yml を指定した swagger-ui が見れるようになります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/1d80e5be-47d9-4b67-0bcc-d7c130037cde.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/4d491ef6-1465-3825-a3d3-7124e933dada.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/881361ff-d5aa-6b54-ecba-e59ba55ce4bc.png)


## yaml に書いたとおりの動作をするサーバーを用意する
↑ の openapi-docker-compose.yml の以下の部分です。
今回使ったのはこちら https://stoplight.io/open-source/prism/

```yaml
  swagger-server:
    image: stoplight/prism:3
    ports:
      - "4011:4010"
    command: mock -h 0.0.0.0 /openapi-sample.yml
    volumes:
      - ./openapi-sample.yml:/openapi-sample.yml
    networks:
      - openapi
```

これは何をしてるかというと、下の図の右側、swagger-ui から実際にリクエストを受け付け & レスポンス返却をするサーバーです。
![openapi-server.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/7bef2d87-298c-43c9-2354-b357791e56a9.png)

↓の画面右側、Try it out を押して。。。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/f39001a1-65f3-45ab-0c9d-86a3c12dce8b.png)

リクエストパラメータ入力、execute を押すと実際に curl で http リクエストが localhost:4011 (今回用意したサーバー)に投げられていることがわかります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/275553/ca4badb4-9719-52a3-bc6e-255465748f72.png)

これでモックサーバーとして用意することもできますね。