こんにちは！！！これはHabréに関する私の最初の投稿であり、私自身のために新しいフレームワークを研究した私の経験をあなたと共有したいと思います。
トピックを選択して、チームのプレゼンテーションを準備する時間がありました。スピーカーのEvgenyMarenkovに触発されて、私はこのトピックを選択することにしました。準備の過程で、必要な情報をコンパクトかつ効果的に伝えるために、多くの記事やリポジトリを検索しました。
誰かがSwagger（OpenApi 3.0）を学ぶのに役立つことを願って共有したいと思います。
前書き
あなたの多くがあなたが望むコントローラーのドキュメントを見つけるのに苦労していると私は99％確信しています。多くの場合、すぐに見つけたものの、最終的にはドキュメントに記載されているように機能しないか、存在しなくなったことが判明しました。
今日は、ドキュメントを最新の状態に保つ方法があることを証明します。この中で、Swaggerと呼ばれるSmartBearのオープンソースフレームワークが役立ちます。2016年以降、新しいアップデートを受け取り、OpenAPI仕様として知られるようになりました。
Swaggerは、RESTfulAPI仕様のフレームワークです。その美しさは、仕様をインタラクティブに表示できるだけでなく、リクエストを送信できること、いわゆるSwaggerUIにあります。
Swagger API仕様に従ってクライアントまたはサーバーを直接生成することもできます。このためには、SwaggerCodegenが必要です。
基本的なアプローチ
Swaggerには、ドキュメントを作成するための2つのアプローチがあります。
ドキュメントはあなたのコードに基づいて書かれています。
このアプローチは「非常に単純」と位置付けられています。プロジェクトにいくつかの依存関係を追加し、構成を追加するだけで十分です。必要なドキュメントはすでに用意されていますが、必要な説明はありません。
プロジェクトコードは、その中の豊富な注釈と説明からあまり読みにくくなります。
すべてのドキュメントは私たちのコードで書かれます（すべてのコントローラーとモデルは一種のJava Swaggerコードに変換されます）
このアプローチは、可能であれば使用することをお勧めしませんが、統合するのは非常に簡単です。
ドキュメントはコードとは別に書かれています。
このアプローチには、Swagger仕様の構文に関する知識が必要です。
JAML/JSON , Swagger Editor.
Swagger Tools
Swagger OpenAPI framework 4 :
Swagger Core - Java Annotation.
Swagger Codegen - .
Swagger UI - , . , .
Swagger Editor - YAML JSON .
.
Swagger Core
Swagger Code - Java- OpenAPI
Swagger Core , :
Java 8
Apache Maven 3.0.3
Jackson 2.4.5
, :
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.1.6</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.2</version>
</dependency>
maven , YAML
<plugin>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>0.3</version>
<executions>
<execution>
<phase>integration-test</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<configuration>
<apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
<outputFileName>openapi.yaml</outputFileName>
<outputDir>${project.build.directory}</outputDir>
</configuration>
</plugin>
.
Swagger . , API, API
@Bean
public GroupedOpenApi publicUserApi() {
return GroupedOpenApi.builder()
.group("Users")
.pathsToMatch("/users/**")
.build();
}
@Bean
public OpenAPI customOpenApi(@Value("${application-description}")String appDescription,
@Value("${application-version}")String appVersion) {
return new OpenAPI().info(new Info().title("Application API")
.version(appVersion)
.description(appDescription)
.license(new License().name("Apache 2.0")
.url("http://springdoc.org"))
.contact(new Contact().name("username")
.email("test@gmail.com")))
.servers(List.of(new Server().url("http://localhost:8080")
.description("Dev service"),
new Server().url("http://localhost:8082")
.description("Beta service")));
}
, .
:
@Operation - HTTP .
@Parameter - OpenAPI.
@RequestBody -
@ApiResponse -
@Tag - OpenAPI.
@Server - OpenAPI.
@Callback -
@Link - .
@Schema - .
@ArraySchema - .
@Content - .
@Hidden - ,
:
@Tag(name = "User", description = "The User API")
@RestController
public class UserController {}
@Operation(summary = "Gets all users", tags = "user")
@ApiResponses(value = {
@ApiResponse(
responseCode = "200",
description = "Found the users",
content = {
@Content(
mediaType = "application/json",
array = @ArraySchema(schema = @Schema(implementation = UserApi.class)))
})
})
@GetMapping("/users")
public List<UserApi> getUsers()
Swagger Codegen
Swagger Codegen - , API ( SDK), OpenAPI.
/ :
API clients:
Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured)
Kotlin
Scala (akka, http4s, swagger-async-httpclient)
Groovy
Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations)
Haskell (http-client, Servant)
C# (.net 2.0, 3.5 or later)
C++ (cpprest, Qt5, Tizen)
Bash
Server stub:
Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST)
Kotlin
C# (ASP.NET Core, NancyFx)
C++ (Pistache, Restbed)
Haskell (Servant)
PHP (Lumen, Slim, Silex, Symfony, Zend Expressive)
Python (Flask)
NodeJS
Ruby (Sinatra, Rails5)
Rust (rust-server)
Scala (Finch, Lagom, Scalatra)
API documentation generators:
HTML
Confluence Wiki
Other:
JMeter
, , Swagger:
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>2.4.18</version>
</dependency>
OpenApi 3.0, :
<dependency>
<groupId>io.swagger.codegen.v3</groupId>
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>3.0.24</version>
</dependency>
maven , .
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>3.3.4</version>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<generatorName>spring</generatorName>
<inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
<output>${project.build.directory}/generated-sources</output>
<apiPackage>com.api</apiPackage>
<modelPackage>com.model</modelPackage>
<supportingFilesToGenerate>
ApiUtil.java
</supportingFilesToGenerate>
<configOptions>
<groupId>${project.groupId}</groupId>
<artifactId>${project.artifactId}</artifactId>
<artifactVersion>${project.version}</artifactVersion>
<delegatePattern>true</delegatePattern>
<sourceFolder>swagger</sourceFolder>
<library>spring-mvc</library>
<interfaceOnly>true</interfaceOnly>
<useBeanValidation>true</useBeanValidation>
<dateLibrary>java8</dateLibrary>
<java8>true</java8>
</configOptions>
<ignoreFileOverride>${project.basedir}/.openapi-generator-ignore</ignoreFileOverride>
</configuration>
</execution>
</executions>
</plugin>
.
codegen help , Swagger Codegen:
config-help -
generate -
help - openapi-generator
list -
meta - Codegen. .
validate -
version - ,
validate, generate, Client Java
java -jar openapi-generator-cli-4.3.1.jar validate -i openapi.yaml
java -jar openapi-generator-cli-4.3.1.jar generate -i openapi.yaml -g java --library jersey2 -o client-gener-new
Swagger UI
Swagger UI - API - . OpenAPI ( Swagger), .
Swagger UI pet-project:
"Try it out", :
Swagger Editor
Swagger Editor - Swagger API YAML . Swagger JSON Swagger ( , . .).
OpenAPI 3.0 . , :
openapi
info
servers
paths
components
security
tags
externalDocs
- Swagger Swagger : , Swagger UI. Swagger .
Swagger , , . , X- , .
openapi. OpenAPI. Swagger swagger:
openapi: "3.0.2"
info API, , , , , . .
info:
title: "OpenWeatherMap API"
description: "Get the current weather, daily forecast for 16 days, and a three-hour-interval forecast for 5 days for your city."
version: "2.5"
termsOfService: "https://openweathermap.org/terms"
contact:
name: "OpenWeatherMap API"
url: "https://openweathermap.org/api"
email: "some_email@gmail.com"
license:
name: "CC Attribution-ShareAlike 4.0 (CC BY-SA 4.0)"
url: "https://openweathermap.org/price"
servers , API. - URL, . servers . URL-:
servers:
- url: https://api.openweathermap.org/data/2.5/
description: Production server
- url: http://beta.api.openweathermap.org/data/2.5/
description: Beta server
- url: http://some-other.api.openweathermap.org/data/2.5/
description: Some other server
paths - “ ” OpenAPI. path operations - GET, POST, PUT, DELETE:
paths:
/weather:
get:
components OpenAPI. components , . API parameters responses components
Conclusions
(Swagger UI, Open Specifiation)
Java, PHP, .NET, JavaScrypt (Swager Editor, Swagger Codegen)
.
, ,