SwaggerのAPI定義からPDFドキュメントを生成する

前回はASP.NET CoreのWeb APIプロジェクトにSwaggerを組み込んでAPIのドキュメントをブラウザ上に表示させるところまで実行しました。

これはこれで手軽にAPIの仕様を確認出来て便利なのですが、受託開発の際の納品物としてお客様に渡すには少し不便です。「納品は紙（PDF）で」と言われる事がまだありますよね？

ブラウザに表示されているものを印刷して渡してしまっても良いかもしれませんが、それだと今ひとつ見栄えが良くないので出来ればもう少しきれいなPDF文書を自動生成したいところです。

そこで調べたところ、次のような事が分かりました。

● swagger2markup-cli を使えばSwaggerが生成するJSONファイルから静的なHTMLやMarkdown、AsciiDoc形式のドキュメントなどを生成する事が出来る。

● asciidoctor-pdf を使えばAsciiDoc形式のドキュメントをPDFファイルに変換する事が出来る。

参考：
goa tips: swagger-ui がサービスできないときのドキュメントどうする問題 - 押してダメならふて寝しろ

asciidocをPDFに変換してみた（asciidoctor-pdf）

今回はこれらを使って

swagger.json → AsciiDoc → PDF

という流れでドキュメントを生成する事にします。


まず前提条件として、swagger2markup-cliを使うにはJavaのインストールが必要で、asciidoctor-pdfを使うにはRubyのインストールが必要になります。

Macで開発しているのあれば通常は両方とも既に入っていると思います。Windowsの場合はchocolateyを使えば簡単にインストール出来ると思います。



1. swagger2markup-cliでAsciiDocファイルを生成する

下のURLからjarファイルをダウンロードします。

https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup-cli/

ダウンロード後、コマンドラインから下記を実行します。

java -jar ./swagger2markup-cli-1.3.1.jar convert -i [swagger.jsonへのパス] -d ./adoc

[swagger.jsonへのパス]の部分は 「http://localhost:49879/swagger/v1/swagger.json」のようにURLを指定しても良いし、「./swagger.json」のようにあらかじめダウンロードしておいたJSONファイルを指定しても構いません。

エラーが出ずに成功すれば、adocフォルダには overview.adoc, paths.adoc, definitions.adoc, security.adoc の4つのファイルが出来ているはずです。ファイルが分かれていると次のステップで困るので、1ファイル(out.adoc)に結合しておきます。

cat adoc/overview.adoc adoc/paths.adoc adoc/definitions.adoc > adoc/out.adoc

(security.adocの内容は特に必要がなかったので除外しました。)




2. asciidoctor-pdfでPDFファイルを生成する

gemコマンドでasciidoctor-pdfをインストールします。

gem install --pre asciidoctor-pdf

あとは入力と出力を指定して実行するだけです。

asciidoctor-pdf -o pdf/out.pdf adoc/out.adoc

これでpdfフォルダにout.pdfファイルが生成されます。サンプルはこんな感じです。

デフォルトのスタイルが物足りなければ、テーマを自作して色々とカスタマイズ出来るようです。

asciidocをPDFに変換してみた（asciidoctor-pdf）

さて、ここまででWeb APIからPDFドキュメントを生成する事が出来ました。ただ、APIに変更が発生する度にコマンドを打ち込んでPDFを再生成するのはちょっと面倒です。

そこで次回は、今流行りの「Continuous Integration（CI）」なるものを使ってソースコードの変更をプッシュするだけで自動的にPDFドキュメントが更新される、という事にチャレンジしてみたいと思います。

次回： GitLab CIを使ってWebAPIのPDFドキュメント生成を自動化する

ASP.NET WebAPIにSwaggerを組み込む

1. ASP.NET Core Web APIを新規作成する

Visual Studio 2017でASP.NET CoreのWeb APIプロジェクトを新規作成します。

デフォルトでControllersフォルダの中にValuesControllerがあるので、この名前をProductsControllerに変更し、さらにUsersControllerを追加します。

新規にResourcesフォルダを作成してその中にProductクラスとUserクラスを作成しておきます。

その後ProductsControllerとUsersControllerを編集してダミーのデータをJSONで返す様にした状態のソースコードが下記になります。（コミットにbefore-swaggerタグが付いています。）

https://github.com/mikehibm/AspNetCoreWebApiSwagger/tree/before-swagger

Ctrl+F5キーで実行すると商品とユーザーの情報がJSONで返って来るのが分かります。

この状態でWeb APIとしては動いているので、次にSwaggerを組み込んでAPIのドキュメント（メタ情報）に外部からアクセス出来るようにしてみます。

2. Swaggerを組み込む

Visual Studio内でPackage Managerコンソールを開いて、次のコマンドを打ち込みます。

Install-Package Swashbuckle.AspNetCore

その後、下のサイトを参考にStartup.csファイルを編集します。と言っても数行を追加するだけなので簡単です。

ASP.NET Web API Help Pages using Swagger

編集後の Startup.cs は下の状態になります。




この状態でCtrl+F5キーを押して実行し、http://localhost:xxxxxxx/swagger/ のURLを開くと、Swagger UIの画面が開いてAPIのドキュメントを閲覧する事が出来るようになっています。

ただこの段階ではせっかくソースコードに書き込んだコメントが反映されていないので、次にそれらが反映されるようにします。

3. XMLコメントをSwaggerに反映させる

まず、プロジェクトの設定で「XMLドキュメントファイル」の自動生成を有効化しておく必要があります。

この状態で一旦プロジェクトをビルドすると、指定したファイル名でXMLファイルが出来るはずです。このファイルをVisual Studioのソリューションエクスプローラ上で右クリックして、「プロジェクトに含める」を選択しておきます。

さらに、XMLファイルを選択した状態でF4キーを押してプロパティウインドウを表示し、下のようにプロパティを変更しておきます。これは後でこのプロジェクトをPublishする際に必要になります。

次に、Startup.csファイルの中で services.AddSwaggerGen() メソッドを呼んでいる箇所があるので、そのブロック内に下の3行を追加します。

var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "MySampleWebApi.xml");
c.IncludeXmlComments(xmlPath);

これで再度実行するとソースコード内でクラス単位やメソッド単位で「///」を使って書いたコメントがSwagger UIの画面にも反映されます。

4. まとめ

ASP.NET CoreのWeb APIプロジェクトにSwaggerを組み込んでAPIのドキュメントを表示させるようにする事は、上の通りかなり手軽に出来ます。

ASP.NET Coreでなく従来のASP.NET MVCのプロジェクトでもほぼ同じ手順でSwaggerの組み込みが可能です。

次回はSwaggerが生成した情報を使ってPDFドキュメントを生成する方法を書いてみたいと思います。

ビットコインは通貨として生き残るのか？

世間ではビットコインの分裂騒動が話題になっていますが、その話ではなく、

この本を読み終わってのメモです。




『これでわかったビットコイン [生きのこる通貨の条件]』　斉藤 賢爾  (著)


2014年の本ですがこれからビットコインについて知りたいという人には十分役に立ちます。

本書は「入門編」「使い方編」「そもそも編」「しくみ編」の4部で構成されています。この中で「そもそも編」ではビットコインに否定的な意見を持つ筆者の視点を知ることが出来ます。

BTCの発行量上限が2100万と決まっている事について、筆者は「インフレ撲滅への開発者の強い意志」が反映されたものだと述べ、「でもそもそもインフレって悪いこと？」と疑問を投げかけます。

"たしかに、貨幣を持っている人たちにとっては重大な問題でしょう。みずからの資産が目減りしていくことを意味しているからです。" (p.66)

"逆に、デフレ状態では、商品にたいして貨幣の価値が相対的に上がります。これは富める者たちにとっては資産が自動的に増えることを意味します。" (p.66)

"ビットコインではデフレが起きるような設計がされていますが、うがった見方をすると、富める者たちがそれを利用してさらに儲けようとしている、ともいえるかもしれません。" (p.66) 

"貨幣が希少で、かつ、貨幣がなければ何もできない世の中に生きていると、私たちは、どうにかしてそれを手に入れなければならなくなります。そして、貨幣を持っている人の言うことを聞くようになります。それは、自分が支配される立場におかれることを意味します...(略)" (p.69)

「通貨・貨幣とはなにか」について自分なりに考える良いきっかけになりました。

たしかに、発行数上限が近づくにつれて希少性が上がり「先行者有利」なまま「持てる者」と「持たざる者」の格差が指数関数的に広がっていく現状のビットコインの設計については、「これが本当に最善なのか」今一度じっくりと考えないと行けないのではないかと思いました。


この辺りの「より良い通貨の設計」というテーマについては岩村充教授の『中央銀行が終わる日: ビットコインと通貨の未来』でより詳細に議論されているのでこちらも一緒に読むと面白いです。



ビットコインのPoWの仕組み等についてさらに詳細に知りたい方には大石哲之さんの『ビットコインはどのようにして動いているのか？』(Kindle本)がオススメです。