OpenAPI

概要

OpenAPIはREST APIのインターフェースを記述するための仕様。仕様に基づいて見やすいページにエクスポートしたり、モックサーバを起動できる周辺ツールが開発されている。

Memo

ロゴ設定

エクスポートしたときのロゴ画像を設定できる。 

info:
  x-logo:
    url: https://example.com/sample.png

タグの表示名

エクスポートしたときのタグの表示名を設定できる。 

tags:
  - name: Setting
    x-displayName: ⚙️設定
    description: |
      これは設定

Tasks

DONE 雛形を作成する

マイベストを作る。ファイル分割をしてわかりやすくした。

DONE ポータブルなバリデーションツール

ポータブルに使える、実装と設計の差分を調べるCLIツールを作る。

DONE リファクタ [4/4]

  • ファイル分割
  • CLIコマンド化
  • テストできるようにする
  • docker-composeで起動できるようにする
    • サーバをdockerで起動すると、ホストとポートが異なるので正しくチェックできない
    • dockerを使わずにテスト実行時にGoでサーバを立てるようにした(これがベスト)

DONE 関数を分割

でかいので分ける。

CLOSE カバレッジ表示できるようにする

スキーマのパス一覧を使って全体がわかるので、そこからどこまでカバーしてるか計算する。

DONE テスト用ライブラリとして使えるようにする

assert的な感じで使えるようにする。

Reference

oneOf, anyOf, allOf, not

allofでコンポーネントを組み合わせ、共通化できる。

freee/freee-api-schema: schema file of freee API

freeeのAPIスキーマ。openapiの参考にする。

Archives

DONE OpenAPIの使い方を調べる

API設計・ドキュメント作成をスムーズに行えるようにする。

  • モックサーバ
  • PDF生成

まあ、楽にできる。いくつかの例からyamlを覚えればいいだけだ。あとは継続的にドキュメントをアップデートできる仕組み…たとえば実装と合っているかテストする(RailsでいうところのCommitee)を入れれば、完璧。

DONE my_openapi整理