1. Experience Swagger - hikarizhen/research-swagger GitHub Wiki
変化し続ける要件に対応するために、API経由で連携するマイクロサービス的アーキテクチャが増えてきています。
従来のモノリシックなアプリケーションについて、機能間のインターフェイスをどう管理するかという話が来ました。
Swaggerとは？ 簡単に言えば、APIドキュメントを作成してくれるツールです。
RESTful APIのドキュメントや、サーバ、クライアントコード、エディタ、またそれらを扱うための仕様などを提供するフレームワークです。
=The World’s Most Popular Framework for APIs= と言われています。
企業経営は、意思決定の方式によって、「トップダウン経営」と「ボトムアップ経営」に分かれます。
「トップダウン経営」とは、経営者や経営幹部が意思決定した内容に基づいて、現場従業員が行動することを徹底する経営となります。
一方、「ボトムアップ経営」とは、現場従業員からの提案を基に意思決定していく経営となります。
Swaggerにて、トップドウン形式とボトムアップ形式があります。
- Swagger EditorでSwagger Specificationを編集、定義
- Swagger CodegenでSwagger Specificationからソースコードを生成
- 既に存在するREST APIのソースコードからSwagger Coreのアノテーションなどを使用しSwagger Specification定義
- 生成されたSwagger SpecificationをもとにSwagger UIによって、REST APIをドキュメント化
どの技術でも、関連用語がわからないと、理解し難しいです。
Swaggerを扱う上で中心となる概念で、Swaggerの仕様に準じた、RESTful APIインターフェイスを記述するためのフォーマット(YAML/JSON)
Swagger EditorによってSpecificationは出来上がったので、ここからはソースコードを生成してみます。
といっても、Swagger Editorを使用している場合には非常に簡単でGenerate ServerかGenerate Clientから生成したいコードの種類を選ぶだけです。
https://swagger.io/docs/specification/about/
https://swagger.io/specification/
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:
Available endpoints (/users) and operations on each endpoint (GET /users, POST /users) Operation parameters Input and output for each operation Authentication methods Contact information, license, terms of use and other information.
API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: OpenAPI 3.0 Specification
Swaggerをベースに作られたRESTful APIインターフェイスを記述するためのフォーマット(JSON)
JavaのコードからSwagger Specificationを生成するためのJavaライブラリ
https://github.com/swagger-api/swagger-core
Swagger Specificationからクライアントコード生成するコマンドラインツール
https://editor.swagger.io/
Swagger Specificationからクライアントコード生成するコマンドラインツール
https://github.com/swagger-api/swagger-codegen
Swagger Specificationから動的にドキュメントを生成するツール
https://swagger.io/tools/swagger-ui/
Swagger Core is a Java implementation of the OpenAPI Specification. Current version supports JAX-RS2.
2.1.6 (current stable) リリース日 2020-12-04
■Prerequisites
- Java 8
- Apache maven 3.0.4 or greater
- Jackson 2.4.5 or greater
1.x系のStable版は 1.6.2 (current stable)
1.6.x 以上は Java8が必要です。
1.5.24 Java7をサポートします。
[Swagger Editor] を利用してAPIを定義する。
https://petstore.swagger.io/#/
「Swagger Codegen 」を利用してソースを自動生成します。
しばらく「Online generators」を利用してサーバー側のソースを生成します。
下記のような感じです。
生成したソースは zip ファイルの形でダウンロードします。
※オンライン生成ガイドライン https://github.com/swagger-api/swagger-codegen#online-generators
生成したソース： https://github.com/hikarizhen/research-swagger/tree/main/gen
$ mvn clean package jetty:run
試してみる。
http://localhost:8080/hello
残念ですが、期待している情報は出力されませんでした。
下記のエラー情報は出力された。
org.glassfish.jersey.message.internal.WriterInterceptorExecutor$TerminalWriterInterceptor aroundWriteTo 重大: MessageBodyWriter not found for media type=text/plain, type=class io.swagger.api.ApiResponseMessage, genericType=class io.swagger.api.ApiResponseMessage.
API定義のところ、text/plain は解析できないかと推察します、
producesに “application/json”を入れ替えます。
再度サーバー側のソースを生成して、ビルドした。
今回は結果は出ました。
$curl http://localhost:8080/hello
{“code”:4,”type”:”ok”,”message”:”magic!”}
出たメッセージは暗黙的な「HelloWorld」ではないです。
修正内容：
gen/jaxrs-server/src/gen/java/io/swagger/api/HelloApi.java
検証してみる：
$ curl http://localhost:8080/hello
{“code”:4,”type”:”ok”,”message”:”hello swagger”}
$ curl http://localhost:8080/hello?name=Cathy
{“code”:4,”type”:”ok”,”message”:”hello Cathy”}
生成したソースにて、仮実装を行う。
src/main/java/io/swagger/api/impl/FileApiServiceImpl.java 仮実装
$ curl http://localhost:8080/file/1
{“id”:”20201220001”,”name”:”file_sample”,”status”:”available”}
$ curl http://localhost:8080/file/2
{“code”:2,”type”:”warning”,”message”:”file is not found.”}
$ curl http://localhost:8080/file/3
{“code”:1,”type”:”error”,”message”:”some error is raised.”}
FileApiのアノテーションについて、
@Produces({ "application/xml", "application/json" })
$ curl http://localhost:8080/file/20201220001
HTTP ERROR 500 エラーが発生しました。理由不明です。
模索してみると、 =@Produces({ “application/json” })= のように使えると、無事に解けました。
理由はなんでしょうか。
一般的な使用シナリオの1つは、 swagger-jaxrs2または新規のJAX-RSベースのプロジェクトに統合します。 プロジェクトのライフサイクル中に同期が維持されるAPI定義を自動的に提供および公開する。
メリット：
API定義を自動的に提供及び公開します。(sagger-ui)
さまざまな言語でのAPIクライアント生成（swagger-codegen）
Swagger uses maven for build and deployment and its artifacts are available at Maven Central.
You can use the maven dependencies with any dependency management system that supports maven dependencies such as Maven, Ivy and Gradle.
If you’re not using Maven, please refer to Not using Maven
Integrating swagger-core into a JAX-RS application can be as easy as adding its dependency to the project POM:
<dependencies>
…
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2</artifactId>
<version>2.1.1</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2-servlet-initializer</artifactId>
<version>2.1.1</version>
</dependency>
</dependencies>
NOTE: Swagger Core 2.X produces OpenApi 3.0 definition files.
If you’re looking for swagger 1.5.X and OpenApi 2.0, please refer to 1.5.X JAX-RS Setup Projects that cannot utilize maven’s dependencies would need to add the dependencies manually.
Since those may change from version to version, the list of dependencies will not be documented here. Instead,
it is advised that you clone the swagger-core repository, go to the directory of the relevant module (artifact) and run mvn dependency:list.
That would give you a list of dependencies required by swagger-core which you would have to include manually in your application.
Keep in mind this requires you to have maven installed but it does not require you to use maven for your project.
※see https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X—Not-using-maven
ポイント：
1.依存関係を手動で追加する必要があります。
2.それらはバージョンごとに変わる可能性があるため、依存関係のリストはここでは文書化されません。
解決方法：
代わりに、swagger-coreリポジトリのクローンを作成し、
関連するモジュール（アーティファクト）のディレクトリに移動して、
mvndependency：listを実行することをお勧めします。