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

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: 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