Webでも組み込みでも、何かのシステムを構築したことがある方ならご存知でしょう。 開発というものは、「プログラムを書く作業」よりも、その前の「仕様を決めて文書化する作業」の方がずっとカロリーが高いものです。 最近ちょっとしたAPIを作る機会があり、やはりAPI仕様設計のしんどさと闘いました。 が、API Blueprintという規格とそれに対応するツールを使うことで、そのしんどさが相当な具合で和らぐことがわかりました。 今回はこのAPI Blueprintを全力で推していく記事です。 API Blueprintとは？ https://apiblueprint.org/ API Blueprintは、APIの仕様設計や連携開発を効率的に進めるためのドキュメント仕様です。 Markdownに従った仕様になっているので、そのまま眺めてもある程度理解できるのですが、Blueprintの強みはなんと
はじめに 最近WebAPIを触る機会があって懐かしくなったので、以前とある案件でかじったAPI Blueprintでも布教してみます。 APIの仕様をMarkdown拡張記法で記述できる言語です。 慣れるまでは正直書きづらいですが、元がMarkdownなのでSwaggerに比べるとまだ書きやすい方だと思います。 今度記事にしますが、先日Frisby.jsというWebAPIのテスティングフレームワークを触るためにJWT認証を使った簡単なWebAPIを作ったので、サンプルとしてAPI Blueprintで仕様書を書いてみました。 FORMAT: 1A HOST: http://localhost/api # Sample API Frisbyを触ってみるために最低限の機能だけで作ったWebAPI ## ユーザ登録 [POST /users] 新規ユーザを登録する + Request (appl
sample.apib �c� �U pfU �U FORMAT: 1A # Sample API ## Sample API について Sample API は、与えられた URL にアクセスしたオーディエンスに対するレコメンド記事を返す、架空の API である。 ## API 共通のエラー形式 ### クライアント側が原因の場合 400 Bad Request を返す。ボディ部は以下の形式とする。 ``` {"message":"エラーメッセージ"} ``` 全APIに共通のエラーメッセージとして、以下を定義する。 | エラーメッセージ | 意味 | |:----------------|:-----| | Missing parameters | 必須(required)のパラメータが1個以上指定されていない | | Invalid parameters | 必須のパラメータが指定さ
「API仕様書を書くことになったけど、どうやって書けばいいかな？」 「API仕様書からそのまま記述したAPIのお試しみたいなこと出来ないかな？」 こんにちは、タカフです。 とある案件でAPI仕様書を書くことになりました。API仕様書って書くのが地味に面倒ですよね。 API仕様書は大抵誰かに見せる為に作るから体裁を整えないといけない。 体裁を整えないといけない＝Excel又はWord又はGoogleDocumentで書く。 でも頻繁にAPI仕様書を書いてるわけではない場合テンプレートなんて無いから、体裁含め書いていかなければいけない。 これがツラい。 なので僕は、API仕様書を書くとしたらMarkdown形式で書いてhtml変換を圧倒的にオススメ致します。 その理由と使い方を下記に述べていきます。 API仕様書をMarkdownで書くメリット API仕様書をMarkdownで書くと以下のよう
- + books: (array[Book]) + + books: (array[Book], fixed-type) 公式にしっかり書いてありますね。無駄にGithubとか調べてしまった。。 何が起きたの？ API BlueprintでAPIドキュメントを作成していたときに、どうにもarrayの中身がドキュメント化されない事が気持ち悪くなったので調べてみた。 例えば。次のドキュメントだとこのように変換される。
はじめに 業務でAPI Blueprint と aglio を使ってAPI仕様書を作成したので、 API Blueprint で仕様書を記述 aglio を使うための Docker 環境の構築 aglio を使って、 API Blueprint で記述したファイルを読みやすいドキュメントに変換 という一連の手順を備忘録として残しておく。 今回作成した、API Blueprint で記述したファイルと、 aglio を使うDocker 環境のリポジトリは以下。 API Blueprintとaglioとは API Blueprint Web APIの仕様を表現するための様々な文法を持つ言語のこと。 記述形式はMarkdown。 ただのテキストファイルなので、Gitなどのバージョン管理ツールとも相性が良い。 公式サイト API Blueprint | API Blueprint aglio ap
API BlueprintでAPI仕様書を書く
ツールが古すぎるのが玉に瑕 関連記事: SwaggerでOpenAPI仕様書を作成、HTMLやMarkdownに変換する みんな大好き仕様書の話 最近のサーバーサイドエンジニアはフロントAPIを作るのがメインの作業になってることが多い。 フロントはReactやVueだったりスマフォアプリだったり。 で、フロント側のエンジニアと会話をするときに必要なのがAPI仕様書。 箇条書きとかAPIの説明書などではAPIの中身はわかっても最終的にどういうデータが取れるかがわからない。 (口頭は論外) そこでAPI仕様書を起こして入力値、出力値(型やフォーマットなども)を明確にする。 LaravelなどではLaravel API Documentation Generatorのようなコメントアウトに記述するタイプもあるが、 コードのコメントアウト部分が重たくなってコードが見辛くなる。 API仕様書で調べる
ローカルで動かそうがDockerで動かそうが、APIを持つアプリを作るとなると自然と一覧が欲しくなるもの。 できれば型や仕様書のフォーマットを... ブラウザで見れる&修正後はDiffが取れる形で欲しいですね。 (自分の関わってたプロジェクトだとExcelにペタペタ定義を書くor貼る仕様書でした。古いとこだと一太郎で作ってた。一太郎2018ってあるんだぜ) [一太郎] ... フォントや段組機能は好きです www.justsystems.com そこでAPI仕様書を簡単に作ろうと思った時に当たった選択肢が、Swagger or API Blueprintでした。 今回はAPI Blueprint触った感じを書きます。 [API Blueprint] API Blueprint | API Blueprint [Swagger] ... こっちの方が The World's Most Pop
API 記述言語や API ドキュメンテーションツールの比較（Swagger、API Blueprint、RAML） - Qiita
API 記述言語や API ドキュメンテーションツールの比較（Swagger、API Blueprint、RAML）swaggerAPIBlueprintramlOpenAPI-Specification 背景 「最近」というには最近すぎる気がしますが、今日のシステム開発では、変化し続ける要件に対応するため、システム自体にも柔軟性がもとめられています。 その中でも、サーバーとクライアント、またはサーバー同士のやり取りのためのインターフェイスである Web API（以下、小面倒なので平たく API と呼びます）は Web システムにとって、もはや欠かせないものだと思います。 その API を設計する際には多くの人が RESTful API を採用するでしょう。 しかし、採用したものの設計方針が人によって微妙にバラつきがあったり、ドキュメントの運用保守ができていなかったり、モックや API コ
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
API Blueprintで仕様書を作成しつつモックサーバも起動する手順 | MONSTER DIVE
API Blueprintのススメ - Qiita
Sample of API Blueprint document
API仕様書はMarkdownで書いてhtml出力がベスト（API Blueprint）
API Blueprint(aglio)で、生成されたSchemaのarrayにitemsがない
Docker環境でAPI Blueprint+aglioを使ってAPI仕様書を作成する - Qiita
API Blueprintで爽やかなAPI仕様書を作る - Ponz Dev Log