Inheritance and Polymorphism
Model Composition In your API, you may have model schemas that share common properties. Instead of describing these properties for each schema repeatedly, you can describe the schemas as a composition of the common property set and schema-specific properties. In OpenAPI version 3, you do this with the allOf keyword: components: schemas: BasicErrorModel: type: object required: - message - code prop
swagger specどうやって管理する問題 - Qiita
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? まえがき 社内向けのメモとして書いたら、「これQiitaに上げたらいいんちゃう？」って言われたので上げます。 ほんとにOpenAPIとかSwagger始めて触るチームで共有する用に書いたので、おかしなところがあったら教えてください。 これ書いてる自分もSwagger始めて触ります。 これ書いたときの状況はこんな感じ。 Webアプリ開発中で、チーム全員がVSCodeを使っている。 チームで使えるSwagger Editorの環境を作った直後。 タスク管理はJIRA 内部ドキュメント系はConfluenceで管理 はじめに Swagger
Swagger定義ファイルからそれなりにいい感じのHTMLで静的なAPIドキュメントを生成する - Qiita
こんな感じ サンプル はじめに この記事で紹介してる手順は下記の参考サイトと全く同じです。 Swagger 定義ファイルから そこそこいい感じの静的 REST API ドキュメント作成する - Witch on the Other Shore 最近じゃSwaggerとかでAPI定義書いてSwagger UIをどっかにホスティングして配布するみたいな感じの開発も普通になってきたけど、いまだに静的なファイルでAPIドキュメントが必要というケースも結構あると思う。 一応 swagger-codegen でhtmlを出力することもできるんだけど控えめに言って見た目がダサいため、今まではSwagger UIの画面をブラウザで開きPDFで出力するみたいな方法でわりと無理やりドキュメントを生成してた。(めんどくさいので当然メンテナンスしなくなる) わざわざ自分でツール作るのもめんどくさくて、何かいい方法
Describing Parameters
Note that parameters is an array, so, in YAML, each parameter definition must be listed with a dash (-) in front of it. Parameter Types Swagger distinguishes between the following parameter types based on the parameter location. The location is determined by the parameter’s in key, for example, in: query or in: path. query parameters, such as /users?role=admin path parameters, such as /users/{id}
REST API仕様からAPIクライアントやスタブサーバを自動生成する「OpenAPI Generator」オープンソースで公開。Swagger Codegenからのフォーク
REST API仕様からAPIクライアントやスタブサーバを自動生成する「OpenAPI Generator」オープンソースで公開。Swagger Codegenからのフォーク RESTful APIの仕様を基に、APIクライアント用SDK、APIクライアントのテスト用にAPIサーバのように振る舞ってくれるスタブサーバ、Webサーバのコンフィグレーション、ドキュメントなどを自動生成してくれる「OpenAPI Generator」がオープンソースとして公開されました。 RESTful API仕様の記述フォーマットは、2015年にマイクロソフトやGoogle、IBMらが立ち上げた「Open API Initiative」が提唱する「OpenAPI Specification」が事実上の業界標準となっており、OpenAPI GeneratorもこのOpenAPI Specificationを基に開
Swaggerで定義したAPI仕様からRetrofitで使用するinterfaceを自動生成してみる Part1 - Qiita
こんにちは。VASILYでフロントエンドエンジニアをしている@Horie1024です。主にAndroidアプリの開発をしています。この記事はVASILY Advent Calendar 2017 3日目の記事になります。 さて、先日potatotips #45 (iOS/Android開発Tips共有会)で「Swaggerで定義したAPI仕様からRetrofitで使用するinterfaceを自動生成してみる」というタイトルで発表してきました。この記事では、potatotipsで発表した内容について掘り下げてご紹介しようと思います。 長くなってしまったのでPart1、Part2に分割してご紹介します。 追記: Part2を公開しました。 https://qiita.com/Horie1024/items/ccfa0ff50c0b4f17b932 どんな内容なのか？ VASILYでは、Andr
swaggerの仕様の確認にOpenAPISpecのrepositoryのjsonschemaを信用しない方が良い - Qiita
swaggerの仕様の確認にOpenAPISpecのrepositoryのjsonschemaを信用しない方が良い。 はじめに swaggerのspecはOpenAPI-Specificationとしてrepositoryがある。 このrepositoryの中に仕様自体のドキュメントもある。ところで、swagger spec(OAS)自体のjsonschemaもここに用意されているのだけれど。これがメンテされてなくて信用できないという話 nullableについて nullを許容するschemaをどのように書くかという話がある。このあたりの話は以下のissueを見るとわかる add "null value support" in spec? · Issue #229 · OAI/OpenAPI-Specification 結論から言うと以下の様になっている。 OAS2.0(swagger s
SwaggerでRESTful APIの管理を楽にする - Qiita
背景 最近は変化し続ける要件に対応するために、システムも柔軟であることが求められています。 そのため、部分的に変更やスケールの可能なシステムを構築し、API経由で連携するマイクロサービス的アーキテクチャが増えてきています。 そういった設計の中で問題になっていくのが、従来のモノリシックなアプリケーションではIDEやコンパイラなどで行っていた、機能間のインターフェイスをどう管理するかという部分です。 Swaggerとは? SwaggerとはRESTful APIのドキュメントや、サーバ、クライアントコード、エディタ、またそれらを扱うための仕様などを提供するフレームワークです。 公式サイトでは、The World's Most Popular Framework for APIsと謳っています。 その理由は、マイクロソフト、Google、IBM、SmartBearなどを大手の企業を含む「Open
Spring Boot + SpringFoxでSwaggerを利用してソースからAPIキュメントを生成する - Qiita
SpringFoxとは 一連のSpringプロジェクトで作成されたWeb APIの仕様書を自動で生成してくれるライブラリです。Springfoxは、実行時に一度アプリケーションをスキャンして、Springの設定、クラス構造、その他様々なコンパイル時に基づくAPIのセマンティクスを推論します。ちなみに、SpringFoxはもともとswagger-springmvcという名前で名を馳せていました。 SpringFoxとSwagger SpringFoxはSwaggerのバージョン1.2とバージョン2.0の両方をサポートしていますが、可能であれば2.0が望ましいです。 SpringFoxの設定 以下はmavenの例ですが、swaggerでドキュメント生成に必要な各種ツール群の依存関係を追加します。 <dependency> <groupId>io.springfox</groupId> <art
Adding Examples
An API specification can include examples for: response MIME types, schemas (data models), individual properties in schemas. Examples can be used by tools and libraries, for instance, Swagger UI auto-populates request bodies based on input schema examples, and some API mocking tools use examples to generate mock responses. Note: Do not confuse example values with the default values. An example is
oneOf, anyOf, allOf, not
OpenAPI 3.0 provides several keywords which you can use to combine schemas. You can use these keywords to create a complex schema, or validate a value against multiple criteria. oneOf – validates the value against exactly one of the subschemas allOf – validates the value against all the subschemas anyOf – validates the value against any (one or more) of the subschemas Besides these, there is a not
REST APIのためのコード生成入門
Swagger Codegenは2015年以来注目を集めており、新興企業からIT複合企業に至る多くの企業が、製品の技術スタックの一部としてSwagger Codegenを利用してAPIクライアント、サーバースタブやAPIドキュメントの生成を行っています。(2018年2月時点でAPIクライアントは30以上の言語、サーバースタブは25以上のフレームワークをサポートしています) 本書はSwagger Codegenを活用してRESTful APIの開発を効率化する方法や、独自の要件を満たすために様々なオプションを使用して生成されるコードをカスタマイズする方法をご紹介します。 原著(English Version): https://gum.co/swagger_codegen_beginner 中国語版(简体中文版): https://gum.co/swagger_codegen_beginne
Authentication
OpenAPI uses the term security scheme for authentication and authorization schemes. OpenAPI 3.0 lets you describe APIs protected using the following security schemes: HTTP authentication schemes (they use the Authorization header): Basic Bearer other HTTP schemes as defined by RFC 7235 and HTTP Authentication Scheme Registry API keys in headers, query string or cookies Cookie authentication OAuth
[swaggo]GoのGoDocを書いたら、Swaggerを出せるやばいやつ - Qiita
swaggo 今回紹介するswaggoはyvasiyarov/swaggerにインスパイアを受けて、作成したOSSになります。現在、yvasiyarov/swaggerは開発が止まっているので、いくつかの問題が放置されたままになっています。（これはOSSなので仕方ないです） swaggoは元の構文をそのまま流用して、機能追加をしているものになります。 Swagger 2.0の対応 複雑な構造体の解析 カスタムヘッダー example value セキュリティ 私がざっと見た限り、上の内容はswaggoで無ければ使えないっぽいです。 Swagger便利だけど、書くのがそもそもだるい 最近になって、よくSwaggerというワードを目にするようになりました。これはとても画期的で、APIに実際にリクエストを投げれるドキュメントが出来上がります。 しかし、このドキュメントのコードを書くのが結構面倒！
![[swaggo]GoのGoDocを書いたら、Swaggerを出せるやばいやつ - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/64ad94339234c0b1b11c01b649a21f84bb137890/height=288;version=1;width=512/https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fcdn.qiita.com%252Fassets%252Fpublic%252Farticle-ogp-background-412672c5f0600ab9a64263b751f1bc81.png%3Fixlib%3Drb-4.0.0%26w%3D1200%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTk3MiZoPTM3OCZ0eHQ9JTVCc3dhZ2dvJTVER28lRTMlODElQUVHb0RvYyVFMyU4MiU5MiVFNiU5QiVCOCVFMyU4MSU4NCVFMyU4MSU5RiVFMyU4MiU4OSVFMyU4MCU4MVN3YWdnZXIlRTMlODIlOTIlRTUlODclQkElRTMlODElOUIlRTMlODIlOEIlRTMlODIlODQlRTMlODElQjAlRTMlODElODQlRTMlODIlODQlRTMlODElQTQmdHh0LWFsaWduPWxlZnQlMkN0b3AmdHh0LWNvbG9yPSUyMzFFMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT01NiZzPTk1NmQ2MzVjNjkzOTk1M2Q1YWQ4NDIxOTY1MGZmMzZm%26mark-x%3D142%26mark-y%3D57%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZoPTc2Jnc9NzcwJnR4dD0lNDBwZWkwODA0JnR4dC1jb2xvcj0lMjMxRTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9MzYmdHh0LWFsaWduPWxlZnQlMkN0b3Amcz1iMTFiNzM4YTliYTQ4MWFlMmNmYmJmOWQ4MjI0M2FhOQ%26blend-x%3D142%26blend-y%3D436%26blend-mode%3Dnormal%26txt64%3DaW4gSEFM44OX44Ot44Kw44Op44Of44Oz44Kw5ZCM5aW95Lya%26txt-width%3D770%26txt-clip%3Dend%252Cellipsis%26txt-color%3D%25231E2121%26txt-font%3DHiragino%2520Sans%2520W6%26txt-size%3D36%26txt-x%3D156%26txt-y%3D536%26s%3Dc5a92231c1d807fbbf9f5a6fe4ded06d)
API テクニカルガイドブック - 政府CIOポータル
API テクニカルガイドブック β版 平成 29 年 8 月 1 日 内閣官房情報通信技術（ＩＴ）総合戦略室 1 【目次】 １ 経緯及び目的..............................................................................................................................................................3 ２ API 設計時の留意事項...........................................................................................................................................4 ２．１ URI 設計及びリクエ
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
GitHub - swaggo/swag: Automatically generate RESTful API documentation with Swagger 2.0 for Go.
GitHub - OpenAPITools/openapi-generator: OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
GitHub - nytimes/openapi2proto: A tool for generating Protobuf v3 schemas and gRPC service definitions from OpenAPI specifications
Flask-RESTPlusでREST APIとSwaggerドキュメントを統合 - Qiita
https://crash.academy/class/213
