refirio.org

Memo

メモ > 技術 > 開発: Swagger
概要
入門
Dockerでの編集
VSCodeでの起動
戻る
■概要

RESTful API を構築するためのフレームワーク

OpenAPI Specification | Swagger
https://swagger.io/specification/

Swagger Editor
https://editor.swagger.io/

Swagger UI
https://petstore.swagger.io/■参考ページ

Swagger が OpenAPI にリネームされて Open API Initiative が誕生してた
https://r2.ag/swagger-to-openapi/

Swaggerの概要をまとめてみた。 - Qiita
https://qiita.com/gcyata/items/342073fa7607fd4082bd

SwaggerでRESTful APIの管理を楽にする - Qiita
https://qiita.com/disc99/items/37228f5d687ad2969aa2

Swaggerとは何か？ - プログラマでありたい
https://blog.takuros.net/entry/2015/12/02/082248

OpenAPI-Specification/3.0.0.md at master - OAI/OpenAPI-Specification
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

Wordな職場にSwaggerを定着させようとして失敗したけど結局定着した話 - Qiita
https://qiita.com/segur/items/26c16d4a5175dbbc7b91■RESTful成熟度レベル

Swaggerを使うなら、RESTful成熟度レベルも意識しておく

RESTful成熟度の3レベルモデルについて知る | NTT Communications Developer Portal
https://developer.ntt.com/ja/blog/17762eeb-56e3-4977-acd7-9934f063f58b

RESTとは何か。 - 自分の仕事を憎むには人生は余りにも短い
http://garapon.hatenablog.com/entry/2016/10/17/REST%E3%81%A8%E3%81%AF%E4%BD%95%E3%81%8B%E3%80%82

RESTとは何か - Qiita
https://qiita.com/aosho235/items/125af74e2eab66c7a816

レベル0〜3まであるが、現状3はあまり使われない。2まで考慮していれば十分
レベル2の理想的なAPIとして Amazon S3 が挙げられるらしい
S3では以下のように、URLに名詞の名前を付けてリソースを区別し、メソッド（GET、POST、PUT、PATCH、DELETE）によって処理内容を区別している

GET /puppy.jpg HTTP/1.1		... 取得
PUT /puppy.jpg HTTP/1.1		... 登録
DELETE /puppy.jpg HTTP/1.1	... 削除

■関連ツール

本当に使ってよかったOpenAPI (Swagger) ツール | Future Tech Blog - フューチャーアーキテクト
https://future-architect.github.io/articles/20191008/■利用例

Swagger UI
https://api.lawapi-prototype-test-elaws.e-gov.go.jp/

法令APIプロトタイプ公開テスト｜デジタル庁
https://www.digital.go.jp/policies/legal-practice/public-test■入門

以下が分かりやすくて情報も新しいので参考になる

OpenAPI (Swagger) 超入門 - Qiita
https://qiita.com/teinen_qiita/items/e440ca7b1b52ec918f1b

Swaggerの記法まとめ - Qiita
https://qiita.com/rllllho/items/53a0023b32f4c0f8eabb

基本的にはオンラインツールで作業できる
Swagger Editor に以下を入力すると、画面右側に Swagger UI の結果が表示される
（ただし「VSCodeでの起動」で紹介するように、ローカルで扱えるツールを導入する方が良さそう）
以下はごく簡易なAPIの例

openapi: "3.0.0"
info:
  title: "アプリAPI"
  version: "1.0.0"
servers: 
  - url: "https://example.com/api/{version}"
    description: "Mobile App API Server"
    variables:
      version:
       default: "v1"
paths:
  "/healthcheck":
    post:
      tags:
        - "User"
      summary: "接続テスト用"
      parameters: []
      responses:
        "200":
          description: "接続テストの結果を返す"
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  message:
                    type: "string"
                example:
                  message: "OK"
  "/users":
    get:
      tags:
        - "User"
      summary: "すべてのユーザを取得"
      parameters: []
      responses:
        "200":
          description: "ユーザオブジェクトの配列を返す"
          content:
            "application/json":
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/User"
  "/user/{userId}":
    get:
      tags:
        - "User"
      summary: "指定したユーザを取得"
      parameters:
        - name: "userId"
          in: "path"
          required: true
          schema:
            type: "integer"
      responses:
        "200":
          description: "ユーザオブジェクトを返す"
          content:
            "application/json":
              schema:
                type: "object"
                items:
                  $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: "object"
      required:
        - "id"
      properties:
        id:
          type: "integer"
        name:
          type: "string"
■Dockerでの編集

サーバ上に置いて
https://github.com/teinen/openapi-sample/blob/master/openapi-sample.yaml
読み込ませて表示する。Swagger Editor の右半分はこれらしい
http://petstore.swagger.io/?url=https://raw.githubusercontent.com/swagger-api/swagger-codegen/master...

が、外に出せない情報を扱う場合はオンラインツールは避けたいところ
その場合Dockerでローカルで動かすことができる
（ただし「VSCodeでの起動」で紹介するように、もっと手軽に扱えるツールを導入する方が良さそう）

swaggerapi/swagger-editor - Docker Hub
https://hub.docker.com/r/swaggerapi/swagger-editor/■Dockerでの実行例

docker-compose.yml
version: '3'

services:
  swagger-ui:
    container_name: swagger-ui
    image: swaggerapi/swagger-ui
    ports:
      - '8081:8080'
    volumes:
      - ../../api/swagger/:/usr/share/nginx/html/swagger

  swagger-editor:
    container_name: swagger-editor
    image: swaggerapi/swagger-editor
    ports:
      - '8082:8080'


以下のとおり実行

$ cd /c/Users/refirio/docker/swagger
$ docker-compose build
$ docker-compose up -d
$ docker-compose down


swagger-ui
http://192.168.99.100:8081/
swagger-editor
http://192.168.99.100:8082/■VSCodeでの起動

※未検証

Wordな職場にSwaggerを定着させようとして失敗したけど結局定着した話 - Qiita
https://qiita.com/segur/items/26c16d4a5175dbbc7b91

【VSCode】おすすめ拡張機能 - Swagger Viewer - 開発覚書はてな版
https://kakkoyakakko2.hatenablog.com/entry/2019/03/24/003000

Swagger Viewer - Visual Studio Marketplace
https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer
Memo

Advertisement
