■目次
概要入門Dockerでの起動
■概要
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 ■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 が挙げられるらしい 以下のように、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) 超入門 - Qiita https://qiita.com/teinen_qiita/items/e440ca7b1b52ec918f1b Swaggerの記法まとめ - Qiita https://qiita.com/rllllho/items/53a0023b32f4c0f8eabb 基本的にはオンラインツールで作業できる Swagger Editor に以下を入力すると、画面右側に Swagger UI の結果が表示される (ごく簡易なAPIの例)
openapi: "3.0.0" info: title: "アプリAPI" version: "1.0.0" 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でローカルで動かすことができる 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/