RESTful APIの仕様書作成ツール Swagger備忘録



Swaggerとは、RESTful APIを定義するフォーマットであるOpenAPI仕様に基づき構築された、API仕様書を記述・作成するための一連のオープンソースツールの総称。

https://swagger.io/

SwaggerはREST APIの仕様書を作成してくれるフレームワーク

## 機能

個人利用用のSwagger
 - Swagger Editor・・・API仕様書を書くためのエディタ
   https://editor.swagger.io/
 - Swagger UI・・・API仕様書からドキュメントを生成する
   https://swagger.io/tools/swagger-ui/
 - Swagger Codegen・・・API仕様書からコードを生成する

VS Code拡張機能
 - OpenAPI (Swagger) Editor

クラウドでのバージョン管理・共有ツール
 - SwaggerHub

## 使い方


### VS Code拡張機能 OpenAPI (Swagger) Editor

https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi

1. OPEN APIの拡張機能のボタンを押す
2. New OpenAPI fileを押す
3. 適当にAPIのJSONを修正する
4. 適当なフォルダにYAMLを保存する
5. Ctrl+Shift+Pを押す
6. Preview Swaggerを実行する

できるのはtry it outでAPIの検証と仕様書のプレヴューまで
デプロイは別の方法

![swagger_vs_code.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/483556/f5367e97-8eb6-6e66-d98b-bd5a6fcaa83e.png)


```YAML:sample.yaml
openapi: '3.0.2'
info:
  title: API Title
  version: '1.0'
  description: |-
    This is a sample Pet Store Server based on the OpenAPI 3.0 specification.  You can find out more about
    Swagger at [https://swagger.io](https://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!
    You can now help us improve the API whether it's by making changes to the definition itself or to the code.
    That way, with time, we can improve the API in general, and expose some of the new features in OAS3.

    _If you're looking for the Swagger 2.0/OAS 2.0 version of Petstore, then click [here](https://editor.swagger.io/?url=https://petstore.swagger.io/v2/swagger.yaml). Alternatively, you can load via the `Edit > Load Petstore OAS 2.0` menu option!_
    
    Some useful links:
    - [The Pet Store repository](https://github.com/swagger-api/swagger-petstore)
    - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
  - url: https://api.server.test/v1
  - url: https://api.server.test/v2
  - url: https://api.server.test/v3
tags:
  - name: test
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: http://swagger.io
  - name: app
    description: Access to Petstore orders
    externalDocs:
      description: Find out more about our store
      url: http://swagger.io
  - name: user
    description: Operations about user
paths:
  /test:
    get:
      tags:
        - test
      responses:
        '200':
          description: OK
    put:
      tags:
        - test
      description: ''
      parameters: []
      responses:
        '200':
          description: OK
    delete:
      tags:
        - test
      description: ''
      parameters: []
      responses:
        '200':
          description: OK
    post:
      tags:
        - test
      description: ''
      parameters: []
      responses:
        '200':
          description: OK
  /app:
    get:
      tags:
        - app
      description: ''
      parameters: []
      responses:
        '200':
          description: OK
    put:
      tags:
        - app
      description: ''
      parameters: []
      responses:
        '200':
          description: OK
  /val:
    get:
      tags:
        - val
      description: ''
      parameters: []
      responses:
        '200':
          description: OK
security:
  - aaa: [aaa]

```


### YAML形式の仕様書のWebページをデプロイ

Swagger UI

https://github.com/swagger-api/swagger-ui


1. index.htmlを作成して、エディターで開く
2. 下記をコピペする

```html:index.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="description" content="SwaggerUI" />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'path to yaml',
      dom_id: '#swagger-ui',
    });
  };
</script>
</body>
</html>
```
3. url: 'path to yaml',をurl: 'http://127.0.0.1:5500/OpenAPI/sample.yaml', のようにサーバーURLへ変更する

仕様書のWebページを参照するには、サーバーを立てる必要がある。
VS CodeのLive Server等で簡単に検証可能

![swagger_ui1.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/483556/3166f544-3fcf-8cce-f38d-a91194704f6a.png)