Create Web API documents

[koda-masaru]

I added the Web API (#760) , so I will create the document.

---

#760 で Web API を追加したので、APIドキュメントを作成する。
APIドキュメントは何で作成するべきかな。Sphinx?
Github Pages で綺麗にわかりやすい WebAPIを公開するには、どのような方法を使うのが良いのか調べる。（誰か知っていたら教えてください）

[griffin-stewie]

参考までに、API ドキュメントに適しているかどうか分かりませんが Read the Docs なんかはどうでしょうか？Markdown でも reStructuredText でもかけるようです。OSS ならばホストもしてくれるようです。

• Read the Docs
• Read the Docsを利用して美しいWebドキュメントを作成する | OSS on Azure 技術ブログ

GitHub Pages だと Hugo を使うイメージですがこれはブログ向けなツールというイメージがあります。

[koda-masaru]

情報ありがとうございます。Read the Docs 調べてみます。

ちなみに、今のところ、ランディングページ＆マニュアルページを GitHub Pages で Jekyll を使って作成しています。

https://information-knowledge.support-project.org/
https://github.com/support-project/knowledge_information

Jekyllもブログ向けのツールという印象なので、Web APIのドキュメントをホストするためには、テーマをいじったりする必要があるかと思ってます。Read the Docs で使われている Sphinxを使って、MarkdownからAPIドキュメントを生成してそれをGitHub Pagesでホストするのも良いかも。

GitHub Pagesだと、プルリクも送ってもらうことができるので便利なので（英語のTypoとか送ってもらえるので助かる）その点で、なんとかGitHub Pageで完結できると良いかなぁ、、と思っています。

[griffin-stewie]

@koda-masaru
私も使ったことがないので勘違いしているかも知れませんが、GitHub 上で管理しているドキュメントのソースコード(Markdown等)を readthedocs.org にホストしてもらう感じです。その際の変換作業も readthedocs.org 側にやってもらえると思います。なので、

• ドキュメントは Markdown で書くだけ
• 書いたものは適宜 GitHub に Push するだけ
• GitHub にドキュメントのソースはあるので PR 等の恩恵も受けられる
• あとは適宜 readthedocs.org 側で生成処理をやってもらう

感じにできるのではないかと思います。

[takelushi]

WebAPI のドキュメント作成は、個人的に Swagger Editor でyamlファイルを記述するのを推奨します。

ローカルで起動して使うこともできますが、ネットに接続してる場合はオンライン版を使えば十分です。

また、ドキュメントのバージョン管理は、yamlファイルのみで済みます。

[koda-masaru]

Swagger も人気ですよね。
WebAPIのモックも簡単につくれますし。

ドキュメントを作らなければ、、、　
と思いながら、機能追加の実装ばかりしている今日このごろです。