swaggerでAPIドキュメントを書いたらめっちゃはかどった話 - kaz29
Swaggerは、REST APIの仕様とそれに関連するツール群の総称です。REST APIの仕様を定義したJSONファイル(Swagger Spec)を軸に以下のようなツールから構成されています。 Swagger UI - Swagger Spec から動的にAPIドキュメントを生成するツール Swagger Editor - Swagger Specのエディタ Swagger Codegen - Swagger Specからクライアントのコードを生成するツール 最近では、Open API InitiativeがAPIの記述のためにSwaggerを採用して話題になりました。 www.publickey1.jp APIドキュメントのメンテは結構面倒 一般的にAPIの仕様書は、古くはExcel/Wordなどを使ったり、最近ではWikiやMarkdown形式で記述したりなどプロジェクトによって
Markdownドキュメントをgithubで管理して、はてなブログでホストする ~ Mackerelの場合 - Hatena Developer Blog
はてなチーフエンジニアの Songmu です。この記事ははてなデベロッパーアドベントカレンダー2015の7日目の記事です。昨日は id:mazco による デザインにおける個性のつけ方 でした。 今日は Mackerel の公開ドキュメントについてのお話です。 Mackerelは以下で公式ドキュメントを英語と日本語で提供しています。 help.mackerel.io help-ja.mackerel.io これらは実ははてなブログでホストしています。 翻訳は日本語を先に書いて、それをチームのネイティブ翻訳者が翻訳するフローになっています。 ドキュメントの運営 告知ブログのようなものなら良いのですが、ドキュメントはその性質上定期的なメンテナンスが必要になります。特に以下の様な点がドキュメントを運営する際に難しいところです。 なんらかの一括修正が必要になった場合に修正点を洗い出して一括で反映す
[Apiary]Markdownで始めるAPI開発とAPIドキュメント作成 | DevelopersIO
APIを作るとき みなさん、毎日API使ってますか？私は、ワンライナーでAPIをコールすることにハマっています。さて、いつも使っているAPIを作る側になったとき、どのように設計していますでしょうか？また、作ったAPIをどのように使ってもらっていますか？そんな疑問に応えるサービスがApiaryです。 Apiaryとは？ Apiaryは、REST APIをサクッと書けるサービスです。また、APIドキュメントも生成してくれます。モックサーバも提供してくれます。API利用サンプルコードも作ってくれます。うん、使わないって選択肢は無いですねｗ。 無料登録すると早速使えるようになります。チームでプライベートなAPI開発をしたければ有料プランを選択してください。 API開発の流れ API開発の流れは、まずはじめにMarkdown形式でドキュメントを書きます。既にサンプルがあるのでこれを使ってみましょう。
![[Apiary]Markdownで始めるAPI開発とAPIドキュメント作成 | DevelopersIO](https://cdn-ak-scissors.b.st-hatena.com/image/square/60d7120d91185f1739fec5fcbd006f066b98e9f6/height=288;version=1;width=512/https%3A%2F%2Fdevio2023-media.developers.io%2Fwp-content%2Fuploads%2F2015%2F02%2Fapiary-logo.png){kind=logo}
JSON Hyper-Schema からAPIドキュメントとGoのコードを自動生成する | The Wacul Blog
３行で言うと herokuが作ってる prmd を使って、JSON SchemaからAPIドキュメントを出力したよ！ スキーマ定義から、GoのAPI実装コードも出力するツールを作ったらめっちゃ捗るよ！ Goのバリデーション用のライブラリも作ったよ！ 今回作ったものの概要とサンプルコード 概要 以前から、APIを開発する上で、以下のようなことが課題となっていました。 そもそもドキュメント書くのがつらい それもあって、ドキュメントより先にコードが変わってしまう ドキュメントと実装の状況の違いが把握しづらい また、ロジックがそんなに複雑ではないAPIでは、実装の作業は リクエストデータのバリデーション 出力データの整形 (フィルタリング) の２つの作業が大きな割合を占めます。 APIの定義ファイルからドキュメントと、バリデーションや出力データ整形のコードを自動生成できれば、大幅に効率が上がると思
REST APIドキュメント作成ツールはapiary.ioが決定版かもしれない - Qiita
背景 APIドキュメントを書くのが楽になるツールまとめ - Qiita iodocsで便利なREST APIドキュメントを作成する - Qiita これまでずっとREST APIドキュメントをwiki上で管理していて、重たいページ上で特殊記法使ったり、スタイルの調整に時間を取られるのが辛かった。そこで良さげなドキュメントツールを色々調べてたんだけど、最終的にapiary.ioが一番良さそうという結論になってきた。 このサービスの主な特徴。 markdown記法でAPIドキュメントを記述できる ドキュメントの生成と同時にAPIのモックサーバを用意してくれる サインアップから5分くらいあればドキュメント公開できる。ドキュメントのホスト先を気にしなくてもいい。 特にドキュメントと一緒にモックを作ってくれるのは他にはないポイントでかなり便利。 使ってみる サインアップはGithubアカウントで h
わかりやすいREADME.mdを書く
GitHubなどに自分のツールやライブラリを公開するとき，README.mdは重要な役割を担っている．レポジトリを訪れたユーザが自分のツールを使ってくれるか否かの第一歩はREADME.mdにかかっている，と言っても過言ではない．実際自分が使う側になったときも，まずREADME.mdを読んで判断していると思う． 成功しているプロジェクトを参考にしつつ，自分が実践していることをまとめておく．ここに書いていることはあくまで（自分の中で）最低限的なものである．プロジェクトが成長していくにつれてREADMEはあるべき姿に成長していくべきだと思う． READMEの役割 README.mdには大きく2つの役割がある． プロジェクト，ツールの使い方，インストール方法 プロジェクト，ツールの宣伝 元々READMEは前者の役割しかなかったが，GitHubの仕組み上，後者の役割も徐々に重要になっている． さらに
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
