![現状の開発手順
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)
カラーミー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 ● 概要 ○ RESTful APIを記述するための仕様 ○ 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: [email protected] 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