背景 最近は変化し続ける要件に対応するために、システムも柔軟であることが求められています。 そのため、部分的に変更やスケールの可能なシステムを構築し、API経由で連携するマイクロサービス的アーキテクチャが増えてきています。 そういった設計の中で問題になっていくのが、従来のモノリシックなアプリケーションではIDEやコンパイラなどで行っていた、機能間のインターフェイスをどう管理するかという部分です。 Swaggerとは? SwaggerとはRESTful APIのドキュメントや、サーバ、クライアントコード、エディタ、またそれらを扱うための仕様などを提供するフレームワークです。 公式サイトでは、The World's Most Popular Framework for APIsと謳っています。 その理由は、マイクロソフト、Google、IBM、SmartBearなどを大手の企業を含む「Open
概要 最近は API Blueprint で仕様書を書くことが多かったのですが、Swagger が世界標準になるかもしれない、ということもあり、開発の効率化を進めるためにも概要をまとめてみようと思った次第です。 Swaggerとは Swagger は RESTful APIを構築するためのオープンソースのフレームワークのことです。「Open API Initiative」という団体がRESTful APIのインターフェイスの記述をするための標準フォーマットを推進していて、その標準フォーマットがSwaggerです。Swaggerには多くの便利なツールが提供されていることもあり、多くのメリットを享受できそうです。 Swagger Spec を書いておけば自動的にドキュメント生成までしてくれ、それだけではなく、ドキュメントから実際のリクエストを投げられる優れものです。 Swaggerのツール群
OpenAPI Specification Version 3.1.1 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here. This document is licensed under The Apache License, Version 2.0. Introduc
Latest version (0.31.2) (2024-01-28) discussion forum | interactive dingus | repository | changelog All versions: 0.31.2 (2024-01-28) (view changes | test cases) 0.30 (2021-06-19) (view changes | test cases) 0.29 (2019-04-06) (view changes | test cases) 0.28 (2017-08-01) (view changes | test cases) 0.27 (2016-11-18) (view changes | test cases) 0.26 (2016-07-15) (view changes | test cases) 0.25 (20
8. 試してみよう V2→V3コンバータ https://openapi-converter.herokuapp.com/ エディタ（V3対応） http://editor.swagger.io/ swagger: "2.0" info: version: "1.0" title: HelloWorld API description: Minimum swagger example. paths: /hello: get: description: Gets greeting message. parameters: - name: target in: query description: Who to greet required: false type: string responses: 200: description: Successful response. schema:
この記事は Open API Advent Calendar 2017 の 1 日目の記事です。 Open API Specification は、 Open API Initiative が策定を進めている REST API を定義するための仕様です。どの URL にどのようなパラメータを渡すとどのような結果が返ってくるかを記述するための JSON/YAML ベースのフォーマットで、ツールやサービスとの連携も図られています。 今年 2017 年は、 3.0.0 がリリースされました。元となった Swagger が 1, 2 で Open API Spec としては最初のバージョンとなります。 構造の改善 が入り、全体的に使い勝手が良くなった・細かいハックをしなくても運用しやすくなったという印象です。 また、 2016年の API Blueprint (apiary) に続き RAML の
Swaggerとは Swaggerは、RESTful APIを構築するためのオープンソースのフレームワークのことを指します。APIをYAMLで定義でき、実際に呼び出すことができるようなインタラクティブドキュメントを生成できます。Amazon API Gatewayで使われていることでも有名です。 概要については下記のブログを参照してください。 (レポート) AWSモバイル/IoTサービス徹底攻略！！ 「Swaggerで始めるモデルファーストなAPI開発」#cmdevio Swagger 3.0とは Swaggerのバージョンについては、現時点では2系がメジャーですが、3系も正式にリリースされたため、3系で書くケースも増えてきました。なお、API Gatewayは現時点では2系をサポートしています。 3系は、「2系でやりたかったけどできない！」という点が数多く改善され、非常に書きやすくなって
swagger & swagger-php & swagger-ui swagger-phpを使ってswagger形式のAPIドキュメントを作成し、swagger-uiを使って参照・実行したい。 （概要、セットアップ等は以前の内容を参照ください。。） swagger-phpで、swagger2.0に対応したドキュメントは下記の２つくらい？？ swagger-php/Examples swagger-explained ちょっと試行錯誤しながらの部分もあったのでメモとして残しておきます。。 環境 FuelPHP APIのURLは192.168.99.100:81 ユーザーとタグというリソースを扱うAPIで、エンドポイントはユーザ関連のCRUDをひととおり作るイメージ アノテーションサンプル コントローラ API全体の定義と、各エンドポイントの定義を記述していく。 基底クラスと各コントローラに
JSON Schemaを作らなければと思っても、つい面倒で先送りにしてしまいがちです。単なるシステム上だけでなく副次的に開発補助の仕組みがあれば、作る意欲もわくでしょう。そこで今回はJSON Schemaファイルを読み込んでAPIドキュメントを生成してくれるソフトウェアを紹介します。 iodocs node.jsとredisの組み合わせで動作します。JSON Schemaファイルを置いておくと、その内容をHTML上に整形して表示してくれます。Webブラウザ上から実際にAPIをコールすることもできるようになっています。 matic maticはnode.jsで作られているコマンドで、特定のフォルダとディレクトリの配置によってJSON SchemaをHTMLドキュメント化します。 JSONSchemaDocStylesheet JSON Schemaに対してXSLスタイルシートを適用することで
最近のウェブ開発では各機能ごとをAPIでつなぎ込む時代になっています。 そのため、各チームが開発をしていく上で、 他のチームにAPIの仕様を伝える方法をきちんとまとめておく必要が出てきています。 そんな中でAPIドキュメントにどのような役割が求められていて どのような選択肢があるか、一旦自分の把握している知識をまとめています。 (ここで書いているAPIは、httpでアクセスしたら、JSON形式でレスポンスを返すウェブサービスのAPIを指しています) APIドキュメントを用意する上で、すぐにぶつかる壁 APIドキュメントを用意する場合に、何も考えずにExcelやwikiにまとめると、早い段階で メンテナンスのコスト の問題にぶつかります。 『APIドキュメントを書く時間がない』 『本当にドキュメント通りの結果が返ってくるか、試してみないとわからない』 『実際に返ってくるAPIとレスポンスが違
こちらの記事はSpeee Advent Calendar 2016の17日目の記事です。 前日の記事は@yhatt のPostCSS は ポストCSS の夢を見るか？です。 今回は新卒エンジニアである私がJSON Schemaの入門的な記事を書かせていただきます。 ##はじめに そもそも JSON Schema とは何やねん！ となる方も多いと思うので簡単に解説しておくと、 json-schema.orgによって開発されているJSON objectを記述したり検証したりするための設計書のようなものです。 この JSON Schema ですが, JSON Schema Core JSON Schema Validation JSON Hyper-Schema の3つの仕様があります。 今回は JSON Schema Core と JSON Hyper-Schema を使って一つのAPIの仕様
JSON Schemaを手作業で作っていくというのは現実的ではありません。システムで用いるものとあって、書き方が分かりづらい部分があったり、バリデーションの条件などは記述が面倒です。 そこで使いたいのがJSON Schema生成ソフトウェアやライブラリになります。各プログラミング言語ごとに存在しますので使いやすいものを選んでください。 JSON Schema Generator JSON Schema GeneratorはWebブラウザ上でJSON Schemaの編集ができます。全体の設定に加えて、各項目単位でバリデーションの設定をビジュアル的に実行できるようになっています。 結果は一行のJSON文字列になりますので、そのまま開発で利用できます。 json-schema-generator Node.jsのライブラリで、可読性の高いフォーマットでJSONフォーマットを定義します。それを j
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
