僕が考えた最強の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を使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保
Qiita API v2のJSON Schemaを公開しました - Qiita Blog
こんにちは、r7kamura です。 最近は主にイカとして活動しており、カラフルな墨を掛け合う日々を送っています。 さて、QiitaおよびQiita Teamでは、Qiita API v2としてデータを操作するためのREST APIを公開しています。これまで開発者向けに APIドキュメント を提供していましたが、今回は主に機械向けのインターフェースとして、JSON Schemaで記述したREST APIのスキーマ定義 (以下スキーマ) を公開することになりました。具体的には、JSON Hyper-Schema draft v4 を利用して定義されています。 http://qiita.com/api/v2/schema Qiita API v2のスキーマの説明Qiita API v2のスキーマの構成について簡単に説明します。スキーマは http://qiita.com/api/v2/sche
PHPでJSONバリデート - YEAH HEY!
2014-05-25 PHPでJSONバリデート PHP phpUnit テスト こちらを参考にさせて頂きました。→ JSON SchemaとPHP - 泥のように KnpJsonSchemaBundle by KnpLabs っていうのがあるみたいなのですが、 require php >=5.4 This bundle is in development stage!!! Do not use it in production. とのことなので、見送り。 justinrainbow/json-schema · GitHub を使うことにします。 composer.json に { "require": { "justinrainbow/json-schema": "~1.3" } } を追加して、 $ php composer.phar update justinrainbow/json
JSON Schema で Web API のスキマを埋めよう
クライアント実装 サーバ実装 仕様 Web API にありがちなこと API ドキュメント リクエスト レスポンス ぶっちゃけAPI の追加時く らいしか更新していない なぜかドキュメントにない属性が 含まれている 手が滑ってドキュメントと若干違う形式の 属性を含めちゃったけどなんとなく通った クライアント実装 サーバ実装 仕様 いまは API Blueprint で頑張ってる (http://apiblueprint.org/) API ドキュメント リクエスト レスポンス Markdown の スーパーセット (ツラい) API Blueprint (YAML 表現) generate mock validate あんまり嬉しく ない なんか別に JSON Schema 書かない といけない クライアント実装 サーバ実装 仕様 今日話したいこと JSON Schema API ドキ
JSON Hyper-Schema からAPIドキュメントとGoのコードを自動生成する | The Wacul Blog
３行で言うと herokuが作ってる prmd を使って、JSON SchemaからAPIドキュメントを出力したよ！ スキーマ定義から、GoのAPI実装コードも出力するツールを作ったらめっちゃ捗るよ！ Goのバリデーション用のライブラリも作ったよ！ 今回作ったものの概要とサンプルコード 概要 以前から、APIを開発する上で、以下のようなことが課題となっていました。 そもそもドキュメント書くのがつらい それもあって、ドキュメントより先にコードが変わってしまう ドキュメントと実装の状況の違いが把握しづらい また、ロジックがそんなに複雑ではないAPIでは、実装の作業は リクエストデータのバリデーション 出力データの整形 (フィルタリング) の２つの作業が大きな割合を占めます。 APIの定義ファイルからドキュメントと、バリデーションや出力データ整形のコードを自動生成できれば、大幅に効率が上がると思
JSON Schema の感じをつかむ • masu-mi's blog(dirty pages)
JSON Schema を使ってみた。今回の内容は2つ。 JSON Schema への参考資料のリンクを整理する PHPでバリデーションのサンプルをメモする JSON Schema について JSON はJavaScriptのオブジェクト表現をベースにしたデータ記述言語で様々なデータ構造を記述できる。 データがあると型・メタ情報を扱いたくなる。JSONデータに対するスキーマ定義の仕様が幾つかある。 JSON Schemaは有力候補の1つ。 JSON Schema 資料集 公式ドキュメントは以下のdraftへのリンクを掲載している。 JSON Schema: core definitions and terminology JSON Schema: interactive and non interactive validation JSON Hyper-Schema: Hypertext
JSON SchemaとPHP
というタイトルで発表してきました。Engine Yardさま、いつも会場提供ありがとうございます。 ( 第72回 PHP勉強会@東京 : ATND ) JSON Schemaというものがあって、すげー応用範囲が広くて、バリデーションなら大体これだけで出来ますよーという内容でした。 スライドはちょっとネタに走ってますが、書いてあることは割と本気です。「JSON SchemaはJSONのバリデーションを行うためのもの」と一般には定義されていますが、JSON互換のデータ構造を持っている動的型付き言語においては、JSON Schemaで言語ネイティブのデータ構造が全てバリデーションできてしまうのです。 JSON Schemaはいまひとつ流行ってない気もしますが、構造そのもののバリデーションに主眼を置いていたり、言語を超えてバリデーションルールを共有できたり、結構おもしろいことができるので、使ってみ
JSON Schemaを上手く運用出来そうなprmdとその周りのお話 - Qiita
最近APIのバリデーションを行うのにJSON Schemaを使おうという話をよく聞くのですが じゃあやってみようとすると、単体のJSONのバリデーションを行うことは出来るけれど それが実際の運用に適用できるようにするためには、 それなりに考えなくてはいけないようです。 JSON Schemaって? JSON Schemaは、文字の通りJSONのスキーマ定義を明確にするものです。 2014/09/07現在、IETFにdraft v4が3つに分割されて公開されています。 JSON Schema Core JSON Schema Validation JSON Hyper-Schema それで、単体のJSONファイルの確認ならばCoreだけで十分なのですが WebサービスのAPIを管理しようとなると、 JSON Hyper-Schemaのほうで定義されているlinksを使って、ひとつのURIに対
JSON SchemaとPHP
その時は最善の実装だと思っていたことでも、月日が立つことで、それは間違いだったと気づくことがあります。 5年という歳月はそれを気づかせるには十分な時間で、 DDDをやり始めた初期の頃に書かれたコードは良くディスられたりしています。 そのコードは何を失敗していたのか？そして、それは改善するために改善した事とは？ BIGLOBEにおける"今"のいいコードの書き方をできる限り具体的な事例を元に紹介します。
JSON Schema と API テスト YAPC::Asia Tokyo 2014
下記勉強会の発表資料です。 --------------------------------------------------------- JSLOVE 〜JavaScriptを愛する人の話を聞いてみよう〜 http://devlove.doorkeeper.jp/events/5811 ---------------------------------------------------------
全てがJSONになる - ✘╹◡╹✘
TL;DR JSON Schemaを使ってこういうことが実現可能になった。 ダミーAPIサーバの提供 ドキュメントの自動生成 APIクライアントの動的定義 APIサーバのバリデータの動的定義 APIサーバのレスポンスの自動テスト JSON Schemaとは JSON SchemaというのはあるJSONのデータ構造を記述するための方法および書式の仕様で、 JSON SchemaもJSONで記述される。 これを利用すれば、リソースベースの(=RESTfulライクな)APIの仕様が簡便に記述できる。 例えば、我々のAPIはレシピとユーザというリソースを扱っていて、 それぞれCRUDのAPIを備えており、レシピはidとtitleとdescriptionという属性を持つ、 という旨をJSON Schemaで表現できる。 なんで最近ちょっと流行ってんの Mobile First、 Service Or
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
SSSSLIDE