Clever Geek Handbook

Swagger (OpenAPI 3.0)

Hallo!!! Dies ist mein erster Beitrag zu HabrĂ© und ich möchte meine Erfahrungen bei der Erforschung eines neuen Rahmens fĂŒr mich mit Ihnen teilen.





Ich hatte einen Moment Zeit, ein Thema auszuwĂ€hlen und eine PrĂ€sentation fĂŒr mein Team vorzubereiten. Inspiriert von der Sprecherin Evgeny Marenkov habe ich mich fĂŒr dieses Thema entschieden. WĂ€hrend der Vorbereitung habe ich viele Artikel und Repositories durchsucht, um die erforderlichen Informationen kompakt und effektiv zu vermitteln.





Jetzt möchte ich es in der Hoffnung teilen, dass es jemandem beim Erlernen von Swagger (OpenApi 3.0) hilft.





EinfĂŒhrung

Ich bin mir zu 99% sicher, dass viele von Ihnen Probleme hatten, die Dokumentation fĂŒr den gewĂŒnschten Controller zu finden. Viele, wenn sie es schnell fanden, aber am Ende stellte sich heraus, dass es nicht wie in der Dokumentation beschrieben funktioniert oder nicht mehr existiert.

Heute werde ich Ihnen beweisen, dass es Möglichkeiten gibt, die Dokumentation auf dem neuesten Stand zu halten. Dabei wird mir das Open Source-Framework von SmartBear namens Swagger helfen. Seit 2016 hat es ein neues Update erhalten und wurde als OpenAPI-Spezifikation bekannt.





Swagger ist ein Framework fĂŒr die RESTful-API-Spezifikation. Seine Schönheit liegt in der Tatsache, dass Sie damit nicht nur die Spezifikation interaktiv anzeigen, sondern auch Anfragen senden können - die sogenannte Swagger-BenutzeroberflĂ€che.





Es ist auch möglich, einen Client oder Server direkt gemĂ€ĂŸ der Swagger-API-Spezifikation zu generieren. Dazu benötigen Sie den Swagger Codegen.





Grundlegende AnsÀtze

Swagger hat zwei AnsÀtze, um Dokumentation zu schreiben:





  • Die Dokumentation basiert auf Ihrem Code.





    • Dieser Ansatz wird als "sehr einfach" positioniert. Es reicht aus, dem Projekt mehrere AbhĂ€ngigkeiten hinzuzufĂŒgen, die Konfiguration hinzuzufĂŒgen, und wir haben bereits die erforderliche Dokumentation, obwohl nicht wie beschrieben beschrieben.





    • Der Projektcode wird aufgrund der FĂŒlle an Anmerkungen und Beschreibungen in ihnen nicht sehr gut lesbar.





    • Die gesamte Dokumentation wird in unseren Code geschrieben (alle Controller und Modelle werden in eine Art Java Swagger Code konvertiert).





    • Es wird nicht empfohlen, den Ansatz nach Möglichkeit zu verwenden, er ist jedoch sehr einfach zu integrieren.





  • Die Dokumentation ist getrennt vom Code geschrieben.





    • Dieser Ansatz erfordert Kenntnisse der Swagger Specification-Syntax.





    • JAML/JSON , Swagger Editor.





Swagger Tools

Swagger OpenAPI framework 4 :





  1. Swagger Core - Java Annotation.





  2. Swagger Codegen - .





  3. Swagger UI - , . , .





  4. 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 . , :





  1. openapi





  2. info





  3. servers





  4. paths





  5. components





  6. security





  7. tags





  8. 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)





  • .





  • , ,











More articles:


All Articles