API Blueprint. A powerful high-level API description language for web APIs. API Blueprint is simple and accessible to everybody involved in the API lifecycle. Its syntax is concise yet expressive. With API Blueprint you can quickly design and prototype APIs to be created or document and test already deployed mission-critical APIs. Tutorial Tools section Focused on Collaboration API Blueprint is bu
【API Blueprintの使い方】Web APIの仕様書を書く・読む・実行する | DevelopersIO
【API Blueprintの使い方】Web APIの仕様書を書く・読む・実行する できればドキュメント書きたくないなー。はやくAPI実装したい！俺の頭の中に全部仕様入ってるから！俺が仕様だ！ ... その仕様、API Blueprintでドキュメントにおこしませんか？ はじめに デバイスが多様化し、その違いを吸収する統一的なインターフェースが求められる昨今、Web APIはその回答のひとつといえます。弊社でも、モバイルアプリとWeb APIを組み合わせてサービスを構築することがあります。 Web APIが登場する開発では、モバイルアプリ（APIクライアント）メンバーと、APIサーバメンバーのコミュニケーションが不可欠です。開発を円滑に進めるために、APIの仕様書 が必要になります。お互いがAPIの仕様を想像して勝手に開発を進めたのでは、いざ結合したときに悲惨な結果になることが目に見えてい
APIドキュメントを生成するためのMarkdown拡張API BluePrintとその周辺のライブラリ - Qiita
API Blueprint(以下Blueprint) は MarkdownファイルからAPIドキュメントやサンプルデータになる JSONを生成する仕様。 一旦決められたフォーマットのJSONに吐き出すので、 それを中心に入出力のライブラリが色々あったりする。 Blueprintのパーサー MarkdownからJSONを出力するために Snow Crashというライブラリを利用する。 後に書くものは大体このSow Crashを利用するので詳細は省略。 BlueprintからAPIドキュメントHTMLを生成する Blueprintを上手く扱うために、 色々なライブラリが用意されている。 aglioはBlueprintから表示用htmlを用意してくれるライブラリ。 # output.htmlにファイル出力 $ aglio -i input.md -o output.html # デフォルトの h
GitHub - danielgtaylor/aglio: An API Blueprint renderer with theme support that outputs static HTML
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
Web API のドキュメンテーションって結構めんどくさい。 どういうフォーマットで書くか悩むし、書いていくと似たような内容を何回も繰り返すことになる。 ドキュメントとは別に開発用のモックも用意しなきゃいけなくて、それとの整合性が…ってな具合に悩みは尽きない。 そんなとき今回紹介する API Blueprint を使うとそういった悩みを減らすことができるかもしれない。 今回使う環境は次の通り。 $ sw_vers ProductName: Mac OS X ProductVersion: 10.11.3 BuildVersion: 15D21 API Blueprint API Blueprint というのは Web API (特に RESTful API) の仕様を記述するための言語仕様を指している。 ただし、これは単なる Markdown で書かれた文章を Web API の仕様書とし
（画像は API Blueprint の Web サイト より転載） GMO アドパートナーズ グループ CTO 室の M. Y.（DevOps ネタ担当）です。今回は、API 開発時に使って便利だったツールの話をします。 きっかけ 最近、私が担当している広告関係のプロダクトに、お客様向けに公開する API を新規追加することになりました。この API はお客様側のエンジニアが利用するため、API 仕様書を作る必要があります。 過去の社内事例では、Word ファイルで API 仕様書を作成して、配布していました。しかし、Word ファイルでは差分を確認しづらいので、API 仕様自体のバージョン管理が大変です。そこで、今回は API 仕様書から配布用の HTML を自動生成することにしました。 API 仕様書を自動生成する技術としては Swagger が有名ですが、今回のプロダクトでは AP
概要 この記事ではAPI Blueprint形式でWeb APIの仕様をMarkdownっぽく記述しつつ、aglioで自動的にドキュメント化してみます。 インストール まずHomebrewでnode.jsをインストールして、npmからaglioのパッケージをインストールします。 (前準備)ダミーのWeb APIを用意する 前準備として、まずはドキュメントを書く対象となる適当なWeb APIを用意します。ここではサンプルとして、以下のサイトに掲載されているPythonのBottleというパッケージで書かれたダミーのRESTful APIを返すサーバを使ってみましょう。 Creating a RESTful Python API with Bottle - Fabrizio (Fritz) Stelluto このサイトのbottle/test2.pyは、最低限のCRUD操作が備わったWeb A
API Blueprint創始者が語るAPIの進歩
API言語は揺籃期にある。その開発者たちは先駆者であり，それぞれの仕事に最適な技術を選択している。今年初めにInfoQは，API仕様の選択肢に関してHacker Newsで交わされた，活発な議論を取材した。 コミュニティでの議論から分かるのは，ただひとつの標準というものは存在しない，ということだ。API開発者たちはAPI BlueprntやRAML，Swaggerなどを積極的に利用すると同時に，コミュニティとして協力して，将来使用される標準の定義に取り組んでいるのが現状だ。 InfoQは先日，ApiaryのCEOであり，API Blueprintプロジェクトの創始者でもあるJakub Nesetril氏と話す機会に恵まれた。 InfoQ: API Blueprintの目的と，開発のきっかけについて教えて頂けますか？ Jakub Nestril: API Blueprintは RAMLより早
GitHub - localmed/api-mock: Creates a mock server based on an API Blueprint
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
aglioでAPI Blueprintを使ったドキュメント作成環境をローカルに構築する - dackdive's blog
（2016/11/24追記） 少々アップデートしました。 （追記ここまで） 以前、API ドキュメンテーションツールを色々検討していて Apiary.io を使ってみたんですが その時一緒に調べて気になっていた aglio というツールも試してみたところ、 どうやら自分にはこちらの方が合ってる気がしたのでインストール方法などメモ。 参考にさせていただいた記事 使用するツールはすべて npm でインストール可能なものだが、環境構築については gulp を使う。 gulpfile.js についてはほとんどこちらのコピー。 API 設計ドキュメントをGitHubのプルリクでレビューしつつ Apiary みたいに使うには - Qiita 特に、md (markdown) ファイルを複数ファイルに分割して管理する方法は非常に参考になりました。 使うツール aglio HTML ドキュメント生成ツール
アプリケーションの分割のアプローチ ●４つのアプローチ - ビジネスファンクション - 動詞／ユースケース - 名詞／リソース - 境界づけられたコンテキスト ● トランザクションの分割 - パイプライン化 (VETRO) - コーディネート (Saga) - 状態更新の非同期化 ( Event History - State Materialize - Domain Specific Query ) This document summarizes a microservices meetup hosted by @mosa_siru. Key points include: 1. @mosa_siru is an engineer at DeNA and CTO of Gunosy. 2. The meetup covered Gunosy's architecture with ov
API BlueprintでAPIドキュメントを作成してGitHub、TravisCI、S3で運用する | DevelopersIO
API BlueprintでAPIドキュメントを作成してGitHub、TravisCI、S3で運用する APIドキュメント作成の経緯 クラスメソッドではモバイルアプリケーションのAPIサーバを作ることが多いのですが、フロントエンド担当者とのやりとりでどうしてもドキュメントが必要になります。今までいろんな形で作ってきたのですがどれも問題がありました。 フリーフォーマットでWikiに書く。いつの間にか誰も管理しなくなる（できなくなる）。そして誰も見なくなる。 コードからドキュメント自動生成の方法のみで運用するとAPIのコードを書ける人しか編集できなくなる 結局待ち時間が発生する フロントの実装者も編集できるようにしたい モックサーバのデータとドキュメントを別々に運用していると、どちらかの更新を忘れる 今回、新しくAPIドキュメントを作るにあたり、今までの問題も踏まえ次のようなフローでドキュメン
api-blueprint/API Blueprint Specification.md at master · apiaryio/api-blueprint
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
API Blueprintとgulp-aglioでいい感じのAPIドキュメントページを作成 - はてなブログ
きっかけ 現在関わっているWebサービスの各種APIをまとめたドキュメントを作りたかった いい感じのHTMLページにして、なるべく簡単に作りたかった Web上のサービスではなくローカルで作りたかった やったこと APIドキュメントの作成は以下の手順で行いました。 1. gulp-aglioをインストール gulp-aglioはAPI Blueprint(後述)で書かれたMarkdownをHTMLにパースするgulpプラグインです。 自分がmacにインストールした手順は以下の通りです。 (1) nodeをインストール Homebrewを使ってnodeをインストールします。 brew install node (2) gulpをグローバルインストール npmでgulpをグローバルインストールします。 npm install -g gulp また、インストールは以下のコマンドで確認します。 gu
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
こんにちは。エンジニアの原です。 突然ですが、仕様書の管理ってしんどいですよね。 ないと困るのはわかっていても、いざ作るとなるとどうも気が乗らない。 Excel や Word のなどを使って作ってしまうと、変更があったときに どこに変更があったのかわかりにくかったりします。 やっぱり履歴を持つようなファイルは Git 管理がしたいですよね。 というわけで、今回は「 Git 管理できる仕様書を作成しよう」をテーマに、 API Blueprint の紹介をしたいと思います。 API Blueprintとは API Blueprint とは Web API の仕様を表現するための言語のことです。 API Blueprint 公式ページ API の仕様を表現するための様々な文法を持っています。 書き方は Markdown と同じ形式ですので、書き方も馴染みのあるものです。何よりただのテキストファイ
Wantedly( https://www.wantedly.com/ )が行っている社内速習会
Another API-Blueprint, RAML and Swagger Comparison
Just a few years back, lack of a standard way to document, govern or describe a contract for the APIs acted as a deterrent to API adoption within the enterprise. WSDL 2.0 and WADL provided early support, but they couldn’t truly capture the essence of RESTful APIs. Recently we have seen the emergence of several description languages. New ways to describe and document APIs have emerged such as Swagg
前々回：API BlueprintでWeb APIのドキュメントを生成する - Qiita 前回：API Blueprintとapi-mockでモックサーバを作成する - Qiita 概要 さて、今回はAPI Blueprintを使って作成したWeb APIがドキュメント通りに動作するかを、dreddを使ってテストします。 dreddとは dreddはAPI BlueprintをベースにしたWeb APIのテストフレームワークです。"Language-agnostic"と謳っているだけあってテストのフックにはnode.js以外にもgoやPython、Rubyなど多様な言語が利用でき、またCircleCIやJenkinsCIなどのCIのサポートもあります。 このように、API Blueprintのエコシステムに乗っかることによって、API Blueprint形式で書いた仕様からaglioを使
APIを作る機会が増えてきている 例えばマイクロサービス間はAPIでやりとりすることが多い。 外部のサービスもだいたいAPIでやりとりする。 社内APIもいくつかあるが、いざ使おうとなるとどんなリクエストを送るべきなのか、またどんなリクエストが返ってくるのかを調べるのが面倒。 API ドキュメントを書くのは大変 フォーマットは？ Markdown? HTML? Text? エンジニア間で書き方がバラバラにならない？ そのドキュメントの内容は今も正しい？ そもそも書くのが面倒… ということで、いい感じのAPIドキュメントツールがほしい API ドキュメントツールに求めること その1 ドキュメントが書きやすい ドキュメントが読みやすい ドキュメントがGitで管理しやすい リクエスト情報、レスポンス情報が見やすい curlですぐに試せるようにサンプルがほしい ドキュメントとコードに乖離がないよう
Introduction to Hariko API Server with API-Blueprint - のらねこの気まま暮らし
はい、harikoの紹介です。 harikoとは hariko harikoとはNodeJS製のAPI MockServerであり、APIドキュメンテーションツールであるAPI Blueprintのエコシステムです。 使い方 npmからインストールして下さい。 npm install -g hariko harikoはAPI-Blueprintのドキュメントをベースにレスポンスを返すAPI Serverを立ち上げるので、 まずはAPI-Blueprintの仕様に沿ったmarkdownが必要です。 # GET /api/message + Response 200 (text/plain) hello world 適当に、 docs/api/message.md とかに保存します。 harikoのサーバを立ち上げます。 CLIから以下のように打ち込んで下さい。 hariko -f 'docs
API Blueprintは、APIドキュメントを記述するためのMarkdown拡張です。おおくのツールが公開されており、htmlに変換したり、mock-serverを立てたりできます。 また、Markdown likeなのでそのままでもGithub等で読めます。便利！ つまり、ルールに従ってMarkdownを書くと、モックやhtmlが出来上がる ということです。最高ですね。 他の方法との比較 公式サイトには、他の方法と比較した時の以下の様な利点が挙げられています。 API Blueprint vs. DIY 車輪の再発明をしてる暇があったらAPI開発しようぜ！ API Blueprintは君にヤバいツールを提供する。それを使ってみんなと議論すれば、あとはドキュメントやテスト、Railsのコードすら自動生成できるんだ。 API Blueprint vs. JSON JSONって人間が書くも
概要 Web APIの開発をするのにとりあえずモックを作成してフロントエンドからアクセスできるようにしたくて、どうしようかなと悩んでたらAPI Blueprintなるものを知ったので、試してみました。 今回はAPIドキュメントを手間なくまとめるツールのご紹介です。 api blueprint https://apiblueprint.org/ こちらの記事を参考にさせてもらいました。感謝！ API BlueprintとdrakovとdreddでAPIドキュメントを書きつつモックサーバを立ててさらにテストを走らせる https://arata.hatenadiary.com/entry/2018/03/22/204723 今回構築した環境をGitHubにUPしていますので、ご参考ください。 https://github.com/kai-kou/api-blueprint-use-aglio
ここから少しアップデートしたのでメモ。 リポジトリ 特徴 markdown -> html への変換には aglio、ローカルサーバーは --server オプションを使う ローカルで markdown ファイルを html に変換するのに aglio を使うところは以前と同じ。 改めて調べてみると、--server というオプションでライブリロード機能つきのローカルサーバーの起動までやってくれるらしく、browserSync は不要だった。 また、ポート番号については README に記載されていないが、-p オプションで指定できた。 参考：Support for different port? · Issue #12 · danielgtaylor/aglio $ ./node_modules/aglio/bin/aglio.js Usage: node_modules/aglio/b
Webでも組み込みでも、何かのシステムを構築したことがある方ならご存知でしょう。 開発というものは、「プログラムを書く作業」よりも、その前の「仕様を決めて文書化する作業」の方がずっとカロリーが高いものです。 最近ちょっとしたAPIを作る機会があり、やはりAPI仕様設計のしんどさと闘いました。 が、API Blueprintという規格とそれに対応するツールを使うことで、そのしんどさが相当な具合で和らぐことがわかりました。 今回はこのAPI Blueprintを全力で推していく記事です。 API Blueprintとは？ https://apiblueprint.org/ API Blueprintは、APIの仕様設計や連携開発を効率的に進めるためのドキュメント仕様です。 Markdownに従った仕様になっているので、そのまま眺めてもある程度理解できるのですが、Blueprintの強みはなんと
WebAPIを開発する場合、APIの利用者向けにAPI仕様書を書くと思います。 API BlueprintというWebAPI仕様書のためのMarkdown記法を拡張した記法があり、これに則って仕様書を書くとスムーズに書くことができます。 今回は、このAPI Blueprintに則ってWebAPI仕様書を書く際のちょっとしたTipsを書いてみます。 前提 ここでは、 API Blueprint形式のドキュメントをテキストエディタで書く。 ドキュメントは、aglioを使ってHTML化する。 を前提としています。 API Blueprint API Blueprintは、公式サイトに、 A powerful high-level API description language for web APIs. とあるように、API仕様書を書くための記法です。 API Blueprintの記法の詳細に
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
API Blueprintとは API Blueprintは、APIドキュメントを記述するためのMarkdown拡張で、 多くのツールが公開されており、自動でhtmlに変換したり、mock-serverを立てたりできます。 環境構築 今回は以下の環境で行いました。 ・Vagrant 1.8.1 ・CentOS release 6.6 (Final) ・Node.jsバージョン: v0.10.45 ・nvmバージョン: 0.31.1 今回やりたいこと web上に下記の画面を表示させる 環境構築 それでは行っていきます。 参考サイト：http://dackdive.hateblo.jp/entry/2015/08/07/181723 私が最終的に入れたNodeモジュール モジュール 説明
（画像は API Blueprint の Web サイト より転載） GMO アドパートナーズ グループ CTO 室の M. Y.（DevOps ネタ担当）です。今回は、API 開発時に使って便利だったツールの話をします。 きっかけ 最近、私が担当している広告関係のプロダクトに、お客様向けに公開する API を新規追加することになりました。この API はお客様側のエンジニアが利用するため、API 仕様書を作る必要があります。 過去の社内事例では、Word ファイルで API 仕様書を作成して、配布していました。しかし、Word ファイルでは差分を確認しづらいので、API 仕様自体のバージョン管理が大変です。そこで、今回は API 仕様書から配布用の HTML を自動生成することにしました。 API 仕様書を自動生成する技術としては Swagger が有名ですが、今回のプロダクトでは AP
GitHub - LucyBot-Inc/api-spec-converter: Convert API descriptions between popular formats such as OpenAPI(fka Swagger), RAML, API Blueprint, WADL, etc.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
GitHub - apiaryio/protagonist: Protagonist is Node.js wrapper for the API Blueprint parser
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
GitHub - calderalabs/rspec_api_blueprint: Autogeneration of API documentation using the Blueprint format from request specs.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
API BlueprintとdrakovとdreddでAPIドキュメントを書きつつモックサーバを立ててさらにテストを走らせる - 日頃の行い
タイトルの通りのことをやってみました。 どんな時にテストがコケるか等の精査が出来てないのでまた続きを書くことになりそうですが、 とりあえずやってみたメモです。 API Blueprint? API Blueprintはmarkdown形式でドキュメントを書けるweb APIのドキュメンテーションを書く用の言語ですかね。 API Blueprint | API Blueprint この形式で書いて別のツールで、モックサーバを起動したりテストを走らせたり出来るみたいです。 API Blueprint Tools | API Blueprint drakov? drakovはblueprintの形式で書かれたファイルを利用してモックサーバを起動できるツールです。 github.com API Blueprintとでググるとapi-mockというものがよく出てきたんですが、 最近メンテされてないよ
概要 restfulなapiを設計すっぞ。となっても、「けど同じ戻り値を何回も書きたくない！めんどくさい！」ってなりますよね。 そんなときに、Data Structuresというデータ型定義の方法が使えると知ったのですが、一部ハマったので書き留めておきます。 Data Structuresについては下記を参考にさせてもらいました。感謝！ api blueprint でData Structuresを用いてIFを定義する https://qiita.com/haseshin/items/1394b0c70e25c9f51762 Data Structuresを利用してみる Data Structuresを利用しない場合、/hoges のGETはリストで、hoges/{id} のGETはオブジェクトで返すわけですが、オブジェクトの内容は同じになります。 今回はサンプルなので、id とname
はじめに 最近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
Markdown Syntax for Object Notation (MSON) is a plain-text syntax for the description and validation of data structures. Quick Links 1 How to Read the Grammar 1.1 Markdown Syntax 1.2 Notational Conventions 1.3 Promises 2 Types 2.1 Base Types 2.1.1 Primitive Types 2.1.2 Structure Types 2.2 Named Types 2.3 Member Types 2.3.1 Property Member Types 2.3.2 Value Member Types 3 Type Declaration 3.1 Named
GitHub - wantedly/apiblueprint-rails: apiblueprint-rails creates API Blueprint boilerplate when calling 'rails g apiblueprint'.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
I am working through some deeper research into the world of API design, and specifically into the world of API definitions. This research involves talking to each of the leading providers, crafting a series of stories along the way, resulting in a white paper that provides an overview of the space and possibly where things are going. During my conversations with Tony Tam (@fehguy) of Wordnik, crea
GitHub - Aconex/drakov: Mock Server that implements the API Blueprint specification
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
API Blueprint | API Blueprint
API Blueprint で Web API の仕様を書く - CUBE SUGAR CONTAINER
API Blueprint で API 仕様書を書いて、配布用の HTML を自動生成する方法
API BlueprintでWeb APIのドキュメントを生成する - Qiita
Apiドキュメンテーションツールを使いこなす【api blueprint編】
GitHub - apiaryio/api-blueprint: API Blueprint
API Blueprint を使って Web API の仕様書を書こう
API Blueprint速習会 @Wantedly
API Blueprintで書いたWeb APIをdreddでテストする - Qiita
API Blueprintとその周辺ツール - Qiita
API Blueprintでハッピードキュメントライフ - Qiita
api blueprintとaglioを利用してAPI仕様書を作成する - Qiita
API Blueprintによるドキュメント開発環境【2016年冬】 - dackdive's blog
API Blueprintで仕様書を作成しつつモックサーバも起動する手順 | MONSTER DIVE
API BlueprintでWebAPI仕様書を書く | SG Labs
GitHub - bukalapak/snowboard: API blueprint toolkit
API BlueprintでAPIドキュメントを生成し表示させてみた - Qiita
API Blueprint で API 仕様書を書いて、配布用の HTML を自動生成する方法
GitHub - subosito/iglo: API blueprint's formatter
api blueprintでData Structuresを利用する際の注意点 - Qiita
API Blueprintのススメ - Qiita
MSON Specification | API Blueprint
The Vision Behind Swagger, API Blueprint and RAML