🍣 🛌 ♻️ Swagger (OpenAPI 3.0) 👶🏾 🙆🏻 ✍🏼

Olá!!! Este é meu primeiro post no Habré e quero compartilhar com vocês minha experiência na pesquisa de um novo framework para mim.

Tive um momento para escolher um tema e preparar uma apresentação para minha equipe. Inspirado pelo palestrante Evgeny Marenkov, decidi escolher este tema. No processo de preparação, pesquisei muitos artigos e repositórios a fim de transmitir de forma compacta e eficaz as informações necessárias.

Agora quero compartilhá-lo na esperança de que ajude alguém a aprender Swagger (OpenApi 3.0)

Introdução

Tenho 99% de certeza de que muitos de vocês tiveram problemas para encontrar a documentação do controlador que desejam. Muitos, se encontraram rapidamente, mas no final descobriram que não funciona conforme descrito na documentação, ou não existe mais.

Hoje vou provar para vocês que existem maneiras de manter a documentação atualizada e nisso contarei com a ajuda do framework Open Source da SmartBear chamado Swagger, que desde 2016 recebeu uma nova atualização e ficou conhecido como a Especificação OpenAPI.

Swagger é uma estrutura para a especificação da API RESTful. Sua beleza reside no fato de que permite não apenas visualizar interativamente a especificação, mas também enviar solicitações - a chamada IU do Swagger.

Também é possível gerar um cliente ou servidor diretamente de acordo com a especificação da API Swagger, para isso você precisa do Swagger Codegen.

Abordagens básicas

Swagger tem duas abordagens para escrever documentação:

A documentação é escrita com base em seu código.
- Essa abordagem é posicionada como "muito simples". Basta adicionarmos várias dependências ao projeto, adicionarmos a configuração e já teremos a documentação necessária, embora não conforme descrito como queríamos.
- O código do projeto se torna pouco legível devido à abundância de anotações e descrições neles.
- Toda a documentação será escrita em nosso código (todos os controladores e modelos são convertidos em uma espécie de Java Swagger Code)
- A abordagem não é recomendada para ser usada se possível, mas é muito fácil de integrar.
A documentação é escrita separadamente do código.
- Essa abordagem requer conhecimento da sintaxe de especificação 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)