🥙 👩🏾‍🎓 🚣🏿 Swagger (OpenAPI 3.0) 🧑🏽‍🤝‍🧑🏽 🗒️ 🎎

Bonjour!!! C'est mon premier article sur Habré et je souhaite partager avec vous mon expérience de recherche d'un nouveau cadre pour moi-même.

J'ai eu un moment pour choisir un sujet et préparer une présentation pour mon équipe. Inspiré par le conférencier Evgeny Marenkov, j'ai décidé de choisir ce sujet. En cours de préparation, j'ai recherché de nombreux articles et référentiels afin de transmettre de manière compacte et efficace les informations nécessaires.

Maintenant, je veux le partager dans l'espoir qu'il aidera quelqu'un à apprendre Swagger (OpenApi 3.0)

introduction

Je suis sûr à 99% que beaucoup d'entre vous ont eu du mal à trouver la documentation du contrôleur souhaité. Beaucoup, s'ils l'ont trouvé rapidement, mais au final il s'est avéré que cela ne fonctionne pas comme décrit dans la documentation, ou qu'il n'existe plus.

Aujourd'hui, je vais vous prouver qu'il existe des moyens de maintenir la documentation à jour et en cela je serai aidé par le framework Open Source de SmartBear appelé Swagger, et depuis 2016, il a reçu une nouvelle mise à jour et est devenu connu sous le nom de spécification OpenAPI.

Swagger est un framework pour la spécification de l'API RESTful. Sa beauté réside dans le fait qu'il vous permet non seulement de visualiser de manière interactive la spécification, mais également d'envoyer des requêtes - la soi-disant interface utilisateur Swagger.

Il est également possible de générer un client ou un serveur directement selon la spécification de l'API Swagger, pour cela vous avez besoin du Swagger Codegen.

Approches de base

Swagger a deux approches pour rédiger la documentation:

La documentation est écrite en fonction de votre code.
- Cette approche se positionne comme «très simple». Il nous suffit d'ajouter plusieurs dépendances au projet, d'ajouter la configuration et nous aurons déjà la documentation nécessaire, bien que pas comme décrit comme nous le souhaitions.
- Le code du projet devient peu lisible à cause de l'abondance d'annotations et de descriptions qu'ils contiennent.
- Toute la documentation sera écrite dans notre code (tous les contrôleurs et modèles sont convertis en une sorte de Java Swagger Code)
- Il n'est pas conseillé d'utiliser l'approche si possible, mais elle est très facile à intégrer.
La documentation est écrite séparément du code.
- Cette approche nécessite la connaissance de la syntaxe de la spécification 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)
.
, ,

Swagger (OpenAPI 3.0)