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形式で記述したりなどプロジェクトによって
僕が考えた最強のAPIドキュメント生成 - 銀の人のメモ帳
2023 追記 2023 年現在では、以下の文章では採用を見送っている OpenAPI を使えば OK という雰囲気です。 Web APIの設計 作者:Arnaud Lauret翔泳社Amazon TL; DR ドキュメント生成にはkevinrenskers/raml2htmlを使った ドキュメントはRAML - RESTful API modeling languageで書いた RAMLにはJSON SchemaとJSONを記載できる APIで返ってくるJSONはRailsアプリのrequest specでJSON Schemaを使ってテストした JSON Schemaはr7kamura/json_worldで生成した ドキュメントに載せる例示のJSONもJSON Schemaからgin0606/screijiを使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保
JS界隈にIDLもしくはd.tsを併記・同梱する文化が根付いてほしい - saneyuki_s log
前置き 最近、ウェッブフロントエンドエンジニアらしく各種JavaScriptのライブラリを眺めて、調査・選定しているのだけれども、その過程を通じたこととして、多くのライブラリが、ドキュメントのAPIの説明が貧弱すぎる。 jQueryのドキュメントが腐っているというのは既に広く知られた事実であると思うし、そうでないならば積極的に既知の事実として腐っている事を広めて行くべきであると強く思うが、jQueryに限らずとも、ドキュメントが満足な形で整理されていないのをひしひしと感じる。 この手のものでよくドキュメント化されている部類だと感じるBackbone.jsですら、仮引数の名称と定義のみしか書かれておらず、肝心の引数が備えるべきメンバや、引数の型情報が明示的に記述されていない。そのため、APIを俯瞰し、自分の欲しい情報がどこに詰まっているのか・どのように取得できるのか・DOM標準もしくはECM
GitHub markdown APIで遊ぶよ
markdownといえば各種言語に実装されていますが、GitHubがWeb API形式で変換ツールを出しているようなので遊んでみました。このAPIを通すと、markdownテキストがHTMLに変換されます。 JSONPで使える奴と、RESTっぽくmarkdownなテキスト自体をPOSTするとHTMLの断片が返ってくるraw APIの2つがあります。 利用上限は一時間あたり5000回と太っ腹。 とりあえず、PHP版：http://tojiru.net/markdown.php <?php if (isset($_POST['markdown'])) { $origin = $_POST['markdown']; $ch = curl_init('https://api.github.com/markdown/raw'); curl_setopt($ch, CURLOPT_RETURNTRAN
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
