Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

カラーミーAPIドキュメントの今後

1,257 views

Published on

GMOペパボ 第1回 EC事業部 TechMTGで使用したスライドです。

Published in: Technology
  • Be the first to comment

  • Be the first to like this

カラーミーAPIドキュメントの今後

  1. 1. カラーミーAPIドキュメントの今後 @Joe_noh / 第1回 EC事業部 TechMTG
  2. 2. 本日のお話 ● 話すこと ○ 現状と問題点 ○ 解決案 ○ 決めないといけないこと ● ゴール ○ 今後の構成についてカラーミー開発者の同意を得る
  3. 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. 4. 課題と解決策 ● 課題 ○ ドキュメントを手で書いている ○ API開発とドキュメント更新とプルリク2回出している ○ デプロイも2回やっている ○ Interpolがもうメンテナンスされてない ● 解決策 ○ Interpolをやめて別の仕様に則ってAPI仕様を書く ○ その仕様からドキュメントを自動生成する
  5. 5. APIドキュメント界隈 ● 仕様たち ○ OpenAPI(Swagger) ○ API Blueprint ○ RAML ● どれがいいの? ○ できることはそれほど変わらない ■ ドキュメント生成 ■ コード(クライアントライブラリ、モックサーバ)生成 ○ 一番コミュニティが大きいOpenAPIに乗ります
  6. 6. OpenAPI ● 概要 ○ RESTful APIを記述するための仕様 ○ Swagger 2.0ベース ○ 3.0.0-RC.0が最新 ● 周辺ツール ○ Swagger Editor ○ Swagger Codegen ○ Swagger UI ○ など
  7. 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. 8. やるべきこと ● OpenAPIに則ってYAMLかJSONを書く ● HTTP越しに取得できるようにする ● ドキュメントに変換して公開する
  9. 9. OpenAPIに則ってYAMLかJSONを書く ● YAMLかJSONに仕様を書く ○ YAMLの方が書きやすいのでYAMLで ● 最終的に1ファイルにする ○ 書くときは複数に分割していてもOK ○ デプロイのときに1ファイルにまとめて公開する ■ https://github.com/Joe-noh/yaml_ref_resolver ○ 公開するファイルはJSON ■ YAMLを配っている人たちはあまりいない
  10. 10. HTTP越しに取得できるようにする ● なぜに ○ URL指定を前提としたツールが多い ○ 社外公開できるものは公開しておくと可能性が広がる ● どこで ○ 例えば https://api.shop-pro.jp/v1/spec.json ○ APIに自分を説明させる
  11. 11. ドキュメントに変換して公開する ● 既存ツールに頼る ○ swagger-ui ○ swagger-codegen ○ ReDoc ○ など
  12. 12. ドキュメント生成ツール ● swagger-ui ○ インタラクティブなドキュメントを生成する ■ http://developer.marvel.com/docs ■ https://usdigitalregistry.digitalgov.gov/ ● swagger-codegen ○ モックサーバなどのコードを生成する ○ HTML用のテンプレが2つある
  13. 13. ドキュメント生成ツール ● ReDoc ○ 動的にドキュメントを描画するAngularアプリケーション ○ カスタマイズはまだあまりできない ■ ロードマップには入っている ■ 将来的にある程度できるようになりそう ○ 利用例 ■ https://rebilly.github.io/RebillyAPI/ ■ https://docs.docker.com/engine/api/v1.26/ まずはこれでいいんじゃないか感があります
  14. 14. まずは ReDoc でいいんじゃないか感 ● 工数は抑えたい ● ちょっとならカスタマイズできそう ○ ロゴと色をいじるくらい ○ どうしても満足できないときは自作も視野に入れる ■ 突き詰めるとJSONを取ってきてテンプレに当てはめるだけ ● 他のツールへ乗り換えが難しくない ○ OpenAPIのYAMLは書き直さなくていい
  15. 15. クライアント 図 カラーミーAPI New → ② /v1/spec.jsonを取得① ReDocなど含んだ HTML一式を取得
  16. 16. 現状 → 今後 1. APIを実装する 2. interpolのYAMLを書く 3. APIをデプロイする 4. wwwにあるドキュメントを直す 5. wwwをデプロイする 1. APIを実装する 2. OpenAPIのYAMLを書く 3. APIをデプロイする → spec.jsonが更新される → ドキュメントも更新される
  17. 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

×