#92 OpenAPIの話

どうも、esuiです。

本日の1本目は、

OpenAPIの話



最近はGraphQLが話題ですが、敢えてのREST APIの話ということで・・。

OpenAPIとは


スクリーンショット 2017-08-25 21.01.22.png

- Open API Initiative が策定しているREST APIのドキュメンテーション仕様。
- https://www.openapis.org
- https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md

以下のような企業などが参画しています。
スクリーンショット 2017-08-25 21.03.11.png

OpenAPIの歴史


・2010〜
 Wordnikの主導で”Swagger”として開発開始
・2015/3
 SmartBear Softwareが権利を買収
・2015/11
 Open API Initiative発足
・2016/1
 OpenAPI specification v2がGithubに公開
・2017/3
 v3.0.0-rc0 リリース
・2017/4
 v3.0.0-rc1 リリース
・2017/6
 v3.0.0-rc2 リリース
・2017/7
 v3.0.0 リリース予定

類似するもの


- API Blueprint
- JSON Hyper Schema
- RAML

JSON Hyper Schemaしか使ったことがない人の目線です。

特徴


・JSONで記述する
 JSON Schema(Like)+ 独自スキーマ

・ドキュメンテーション機能が豊富
 エンドポイントの仕様以外にもAPIの利用規約やライセンスといった情報も記述できる。
 コメント用のフィールドはリッチテキストで記述でき、周辺ツール にサポートを義務付けている。

・サポートツールが豊富(Swaggerの時点で)
 https://swagger.io/

ちょうど1年前


JSON Schemaを使って以下のことやってます発表をしました。
・APIドキュメントの生成
・APIリクエストのバリデーション
・APIレスポンスのバリデーション
・モックAPIの生成
http://techdev.seesaa.net/article/report_46.html

厳しい


・HTTPヘッダーについて定義できない
・ステータスコード別のレスポンスを定義できない(できても冗長)

ドキュメントのテンプレートファイルに直接記述するなどして回避している。そのため生成されたドキュメントにしか記載がない情報があったりする。

・Rubyの周辺ツールが少ない
・parseとvalidationしてくれる単純なやつがほしい → 無さそう

嬉しい


・定義できる情報量が多い
・ステータスコード別、Content-Type別にレスポンス定義が可能
・HTTPヘッダーについても定義が可能
・認証の仕様についても定義が可能(oauth2など)

最低限欲しいもの


・レスポンスのバリデーション

パーサーを書いた話


https://github.com/smczk/openapi

このパーサーについて、ちょっとした解説をされていました。

・Openapiモジュール
  OpenAPIの定義データを読み込み、OpenapiObjectクラスのインスタンスを生成する
・BaseObjectクラス
  各種オブジェクトクラスの基底クラス
・EnumerableObjectクラス
  子オブジェクトをイテレートするだけのオブジェクトが継承するクラス
・Referableモジュール
  JSON Referenceを解釈する必要があるクラスがインクルードするモジュール

このあたりを参考にされたそうです。
https://github.com/brandur/json_schema
https://github.com/r7kamura/swagger_parser

ということで、実際にこちらを使ってデモをされていました。

スクリーンショット 2017-06-30 14.28.48.png

スクリーンショット 2017-06-30 14.40.52.png

スクリーンショット 2017-06-30 14.42.09.png

スクリーンショット 2017-06-30 14.44.27.png

まとめ


・OpenAPI v3が出るので
・ドキュメンテーション用途ではかなり良さそうに感じました
・とりあえずパーサー書くところから始めました
・rack env 受け取ってバリデーションするrack middlewareを作ろう


REST API 仕様の標準化をするにあたって、OpenAPIはかなり有望そうですね。




さて、第二部は先週に引き続き、先日入社した新人さんによる自己紹介的発表でした。

これまたこのIT系とは無関係の業種から転職してきたため、
何も知らない状態からドットインストールや、Perl入学式を通してPerlを勉強し、いきなり業務に入って、
git/docker/vi/screenなど、未知のものとどう向き合ってきたか、
チャットを通して聞く事の難しさ、
最初に概要を掴むためにどう意識するようにしてきたか、
技術書を読むよりも実際に手を動かしてコードを書くようにした方が覚えるのも早い事、
などと言った初心者あるある的な気付きなどを発表されていました。

この記事へのコメント