井上 研一 AIモデル（画像認識とか予測とか）を作るお仕事をいくつかやっているのですが、モデルができただけでは何も活用できません。モデルをアプリやシステムに組み込んで、初めて活用の場面が生まれるわけですね。
例えばスマホ用のアプリを作るとして、モデルをアプリ内に完全に組み込んでしまうということもできないわけではないのですが、一般的にはモデルはサーバで動かしてAPIを作り、スマホアプリはAPIを呼び出す形で画像認識や予測を行うことが多いでしょう。
ちょうどそんなお仕事があって、今回初めてSwaggerを使ってAPI仕様を検討し、ドキュメンテーションやらAPIサーバの雛形やらを作ってみることにしました。
Swaggerとは
Swaggerの公式サイトによれば、Swaggerは「チームのためのAPI文書化と設計のツール（API Documentation & Design Tools for Team）」ということのようです。
公式サイトの説明を見るとだいたいSwaggerが何かが分かってくるのですが、
- RESTful API設計の業界標準であるOpenAPI仕様に準拠した、
- 作成、更新、共有のためのツールを（Swaggerが）提供している
- クラウドで提供してるSwagger Hubを使うこともできる
ということで、Swaggerを使ってAPI仕様を検討すればOpenAPI仕様にも準拠した設計ができて、チーム内などでの情報共有もできるというわけですね。
Swagger Editorを使う
そのAPI設計のためのツールがSwagger Editorで、クラウドでも提供されているわけですが、Dockerイメージもあるのでそれを使ってローカルで動かしてみることにします。
docker pull swaggerapi/swagger-editor
docker run -d -p 8888:8080 swaggerapi/swagger-editor
Swagger公式のDockerイメージをプルして、起動します。Swagger EditorはWebアプリでコンテナ内では8080番ポートで使用できます。それをPC上からは8888番ポートでアクセスできるようにしました。
Webブラウザを開いて、localhost:8888にアクセスすると、下記のような画面が表示されます。
デフォルトでは、Swagger PetstoreというサンプルのAPI仕様が表示されます。
このサンプルを見ながら、自分の設計で上書きしていくと良いでしょう。上書きした内容は、FileメニューからYAML形式で保存することができますし、Dockerコンテナを終了してもデータはDockerボリュームに保存されているようなので、次回の起動時も作業をそのまま継続することができます。
Swagger Editorを使ったAPI設計についてはここでは特に触れません。（それもいずれ何か書こうかと思いますが･･･。）
SwaggerファイルをMarkdownに変換する
Swagger Editorでは、YAML形式かJSON形式（コンバート）で保存することができます。
また、Swagger UIというツールを使えば、Swagger Editorの画面右側に表示されているUIを公開することができます。見やすい画面ですし、UI上でAPIコールを試してみることもできるので便利です。
ただ、お客様に仕様書として提出する際にはPDF化したいということもあるはず。
そこで、swagger2markupというツールを使ってみることにします。
swagger2markupはJavaでできているので環境構築がちょっと面倒なのですが、これもまたDockerイメージが提供されているので、それを使うことにします。
まず、Dockerイメージをプルします。
docker pull swagger2markup/swagger2markup
デフォルトでは、AsciiDoc形式にコンバートされるのですが、下記のようなプロパティファイル（config.propertiesというファイル名にしました）を準備すると、Markdown形式にすることができます。ついでに、APIコールの実行サンプルも含めてコンバートするようにします。
swagger2markup.markupLanguage=MARKDOWN
swagger2markup.generatedExamplesEnabled=true
次にこのようなコマンドでswagger2markupを実行します。
引数の -i はSwagger Editorで保存したYAMLファイル、 -f はコンバート後のファイル名（拡張子は自動的に設定されます）、 -c は先ほど作成したプロパティファイルです。
docker run の -v オプションでカレントディレクトリをDockerコンテナ上の /opt にマウントしているので、各引数のパスは /opt から始まるようにしています。
docker run --rm -v $(pwd):/opt swagger2markup/swagger2markup convert -i /opt/swagger.yaml -f /opt/swagger -c /opt/config.properties
これでMarkdown形式にコンバートされるので、後は適当なツール（例えばTyporaやJoplin･･･）を使ってMarkdownを読み込んでPDF化（印刷）すればPDF形式の仕様書のできあがりです。