🤷🏻 🕙 🤞 Swagger (OpenAPI 3.0) 🎢 👋🏼 👩‍👧

¡¡¡Hola!!! Esta es mi primera publicación sobre Habré y quiero compartir con ustedes mi experiencia en la investigación de un nuevo marco para mí.

Tuve un momento para elegir un tema y preparar una presentación para mi equipo. Inspirado por el orador Evgeny Marenkov, decidí elegir este tema. En el proceso de preparación, busqué muchos artículos y repositorios con el fin de transmitir de manera compacta y efectiva la información necesaria.

Ahora quiero compartirlo con la esperanza de que ayude a alguien a aprender Swagger (OpenApi 3.0)

Introducción

Estoy 99% seguro de que muchos de ustedes han tenido problemas para encontrar la documentación del controlador que desean. Muchos, si lo encontraron rápidamente, pero al final resultó que no funciona como se describe en la documentación, o ya no existe.

Hoy les demostraré que hay formas de mantener actualizada la documentación y en esto me ayudarán el framework Open Source de SmartBear llamado Swagger, y desde 2016 recibió una nueva actualización y se conoció como la Especificación OpenAPI.

Swagger es un marco para la especificación de la API RESTful. Su belleza radica en el hecho de que le permite no solo ver la especificación de forma interactiva, sino también enviar solicitudes, la llamada interfaz de usuario Swagger.

También es posible generar un cliente o servidor directamente según la especificación de la API Swagger, para ello necesitas el Swagger Codegen.

Enfoques básicos

Swagger tiene dos enfoques para escribir documentación:

La documentación está escrita en base a su código.
- Este enfoque se posiciona como "muy simple". Nos basta con añadir varias dependencias al proyecto, añadir la configuración y ya tendremos la documentación necesaria, aunque no como se describe como queríamos.
- El código del proyecto se vuelve poco legible debido a la abundancia de anotaciones y descripciones que contiene.
- Toda la documentación estará escrita en nuestro código (todos los controladores y modelos se convierten en una especie de código Swagger de Java)
- No se recomienda utilizar el enfoque si es posible, pero es muy fácil de integrar.
La documentación está escrita por separado del código.
- Este enfoque requiere conocimiento de la sintaxis de la especificación 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)