Clever Geek Handbook

Kesombongan (OpenAPI 3.0)

Halo!!! Ini adalah posting pertama saya di Habré dan saya ingin berbagi dengan Anda pengalaman saya dalam meneliti kerangka kerja baru untuk diri saya sendiri.





Saya sempat memilih topik dan mempersiapkan presentasi untuk tim saya. Terinspirasi oleh pembicara Evgeny Marenkov, saya memutuskan untuk memilih topik ini. Dalam proses persiapan, saya mencari banyak artikel dan repositori untuk menyampaikan informasi yang diperlukan dengan kompak dan efektif.





Sekarang saya ingin membagikannya dengan harapan dapat membantu seseorang dalam belajar Kesombongan (OpenApi 3.0)





pengantar

Saya 99% yakin banyak dari Anda mengalami kesulitan menemukan dokumentasi untuk pengontrol yang Anda inginkan. Banyak, jika mereka menemukannya dengan cepat, tetapi pada akhirnya ternyata tidak berfungsi seperti yang dijelaskan dalam dokumentasi, atau sudah tidak ada lagi.

Hari ini saya akan membuktikan kepada Anda bahwa ada cara untuk menjaga dokumentasi tetap mutakhir dan dalam hal ini saya akan dibantu oleh kerangka kerja Sumber Terbuka dari SmartBear yang disebut Swagger, dan sejak 2016 menerima pembaruan baru dan dikenal sebagai Spesifikasi OpenAPI.





Swagger adalah framework untuk spesifikasi RESTful API. Keindahannya terletak pada kenyataan bahwa ini memungkinkan Anda tidak hanya untuk melihat spesifikasi secara interaktif, tetapi juga untuk mengirim permintaan - yang disebut UI Swagger.





Dimungkinkan juga untuk menghasilkan klien atau server secara langsung sesuai dengan spesifikasi API Swagger, untuk ini Anda memerlukan Swagger Codegen.





Pendekatan dasar

Kesombongan memiliki dua pendekatan untuk menulis dokumentasi:





  • Dokumentasi ditulis berdasarkan kode Anda.





    • Pendekatan ini diposisikan sebagai "sangat sederhana". Cukup bagi kita untuk menambahkan beberapa dependensi ke proyek, menambahkan konfigurasi dan kita sudah memiliki dokumentasi yang diperlukan, meskipun tidak seperti yang kita inginkan.





    • Kode proyek menjadi sangat tidak terbaca dari banyaknya penjelasan dan deskripsi di dalamnya.





    • Semua dokumentasi akan ditulis dalam kode kami (semua pengontrol dan model diubah menjadi semacam Java Swagger Code)





    • Pendekatan ini tidak disarankan untuk digunakan jika memungkinkan, tetapi sangat mudah untuk diintegrasikan.





  • Dokumentasi ditulis terpisah dari kode.





    • Pendekatan ini membutuhkan pengetahuan tentang sintaks Spesifikasi Swagger.





    • 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