Download to read offline
![現状の開発手順
1. APIを実装する
2. interpolのYAMLを書く
3. APIをデプロイする
4. wwwにあるドキュメントを直す
5. wwwをデプロイする
name: show_shop
route: /v1/shop.json
method: GET
definitions:
- message_type: request
versions: ["1.0"]
path_params: {}
query_params: {}
schema: {}
examples: []
- message_type: response
versions: ["1.0"]
status_codes: ["200"]
schema:
type: object
properties:
shop:
type: object](https://image.slidesharecdn.com/ectechmtg-170309095342/85/API-3-320.jpg)
![[出張！雲勉 in Tokyo] Swagger で簡単APIドキュメント作成](https://cdn.slidesharecdn.com/ss_thumbnails/random-160831072101-thumbnail.jpg?width=640&height=640&fit=bounds)
カラーミーAPIドキュメントの今後
- 1. カラーミーAPIドキュメントの今後 @Joe_noh / 第1回EC事業部 TechMTG
- 2. 本日のお話 ● 話すこと ○ 現状と問題点 ○解決案 ○ 決めないといけないこと ● ゴール ○ 今後の構成についてカラーミー開発者の同意を得る
- 3. 現状の開発手順 1. APIを実装する 2. interpolのYAMLを書く 3.APIをデプロイする 4. wwwにあるドキュメントを直す 5. wwwをデプロイする name: show_shop route: /v1/shop.json method: GET definitions: - message_type: request versions: ["1.0"] path_params: {} query_params: {} schema: {} examples: [] - message_type: response versions: ["1.0"] status_codes: ["200"] schema: type: object properties: shop: type: object
- 4. 課題と解決策 ● 課題 ○ ドキュメントを手で書いている ○API開発とドキュメント更新とプルリク2回出している ○ デプロイも2回やっている ○ Interpolがもうメンテナンスされてない ● 解決策 ○ Interpolをやめて別の仕様に則ってAPI仕様を書く ○ その仕様からドキュメントを自動生成する
- 5. APIドキュメント界隈 ● 仕様たち ○ OpenAPI（Swagger） ○API Blueprint ○ RAML ● どれがいいの？ ○ できることはそれほど変わらない ■ ドキュメント生成 ■ コード（クライアントライブラリ、モックサーバ）生成 ○ 一番コミュニティが大きいOpenAPIに乗ります
- 6. OpenAPI ● 概要 ○ RESTfulAPIを記述するための仕様 ○ Swagger 2.0ベース ○ 3.0.0-RC.0が最新 ● 周辺ツール ○ Swagger Editor ○ Swagger Codegen ○ Swagger UI ○ など
- 7. OpenAPIの例 : paths: /pets: get: description: ... operationId: findPets parameters: -name: limit in: query description: ... type: integer format: int32 responses: "200": description: pet response schema: type: array items: $ref: '#/definitions/Pet' default: description: unexpected error schema: $ref: '#/definitions/Error' swagger: "2.0" info: version: 1.0.0 title: Swagger Petstore description: ... termsOfService: http://swagger.io/terms/ contact: name: Swagger API Team email: foo@example.com url: http://example.com license: name: MIT url: http://github.com/.../LICENSE-MIT host: petstore.swagger.io basePath: /api schemes: - http consumes: - application/json produces: - application/json : その他の例は github.com/OAI/OpenAPI-Specification で
- 8. やるべきこと ● OpenAPIに則ってYAMLかJSONを書く ● HTTP越しに取得できるようにする ●ドキュメントに変換して公開する
- 9. OpenAPIに則ってYAMLかJSONを書く ● YAMLかJSONに仕様を書く ○ YAMLの方が書きやすいのでYAMLで ●最終的に1ファイルにする ○ 書くときは複数に分割していてもOK ○ デプロイのときに1ファイルにまとめて公開する ■ https://github.com/Joe-noh/yaml_ref_resolver ○ 公開するファイルはJSON ■ YAMLを配っている人たちはあまりいない
- 10. HTTP越しに取得できるようにする ● なぜに ○ URL指定を前提としたツールが多い ○社外公開できるものは公開しておくと可能性が広がる ● どこで ○ 例えば https://api.shop-pro.jp/v1/spec.json ○ APIに自分を説明させる
- 11. ドキュメントに変換して公開する ● 既存ツールに頼る ○ swagger-ui ○swagger-codegen ○ ReDoc ○ など
- 12. ドキュメント生成ツール ● swagger-ui ○ インタラクティブなドキュメントを生成する ■http://developer.marvel.com/docs ■ https://usdigitalregistry.digitalgov.gov/ ● swagger-codegen ○ モックサーバなどのコードを生成する ○ HTML用のテンプレが2つある
- 13. ドキュメント生成ツール ● ReDoc ○ 動的にドキュメントを描画するAngularアプリケーション ○カスタマイズはまだあまりできない ■ ロードマップには入っている ■ 将来的にある程度できるようになりそう ○ 利用例 ■ https://rebilly.github.io/RebillyAPI/ ■ https://docs.docker.com/engine/api/v1.26/ まずはこれでいいんじゃないか感があります
- 14. まずは ReDoc でいいんじゃないか感 ●工数は抑えたい ● ちょっとならカスタマイズできそう ○ ロゴと色をいじるくらい ○ どうしても満足できないときは自作も視野に入れる ■ 突き詰めるとJSONを取ってきてテンプレに当てはめるだけ ● 他のツールへ乗り換えが難しくない ○ OpenAPIのYAMLは書き直さなくていい
- 15. クライアント 図 カラーミーAPI New → ② /v1/spec.jsonを取得①ReDocなど含んだ HTML一式を取得
- 16. 現状 → 今後 1.APIを実装する 2. interpolのYAMLを書く 3. APIをデプロイする 4. wwwにあるドキュメントを直す 5. wwwをデプロイする 1. APIを実装する 2. OpenAPIのYAMLを書く 3. APIをデプロイする → spec.jsonが更新される → ドキュメントも更新される
- 17. 決めないといけないこと ● リポジトリの名前 ○ ReDocを含んだHTML一式を管理する場所 ●OpenAPI JSONのURL ○ https://api.shop-pro.jp/v1/spec.json ○ https://api.shop-pro.jp/v1/swagger.json ○ https://api.shop-pro.jp/v1/openapi.json ● 新ドキュメントのURL ○ https://shop-pro.jp/?mode=api_interface ○ https://api.shop-pro.jp/v1/docs ○ https://api-doc.shop-pro.jp/v1