Swagger3 annotation usage (Open API 3)

[Use of swagger] 3

Swagger2 (based on openApi3) has been out of maintenance in 2017, and replaced by sagger3 (based on openApi3), and there are almost no documents used by sagger3 in China. Baidu searched for the use of swagger2. This article will introduce how to use swagger2 in java Use openApi3 (swagger3).

Related introduction

Open [API]

OpenApi is the industry’s real api documentation standard, which is maintained by Swagger and listed as an api standard by linux, thus becoming an industry standard.

Swagger

Swagger is an api document maintenance organization, and later became the main definer of the Open API standard. Now the latest version is Swagger3 (Open Api3) released in 2017.
Most people in China are still using the outdated swagger2 (stopped maintenance in 2017 and changed its name to swagger3) . The package name of swagger2
is the same as that of swagger3 .io.swagger.swagger.core.v3

SpringFox

SpringFox is a project (unofficial) maintained by the spring community to help users integrate swagger2 into Spring.
Often used in Spring to help developers generate documentation, and can be easily used in spring boot.
As of April 2020, the OpenAPI3 standard is not supported.

Supplement: 2020.7.14 released 3.0 to support OpenAPI3, github release records , but the official website is not perfect for the 3.0 version related documents, or only swagger 2.0 related.
Upgrade to OpenAPI3 (swagger1.x in java corresponds to OpenAPI2, swagger 2.x corresponds to OpenAPI3) official documentation

3.0 Related Features

  • support Spring 5, Webflux(request map support only, no function endpoints yet),Spring Integration
  • After supplementing the official automatic assembly pringfox-boot-starterof you can directly rely on a dependency
  • Better spec compatibility with 2.0
  • Support OpenApi 3.0.3
  • Light dependency spring-plugin , swagger-core
  • Existing swagger2 annotations will continue to work and enrich the Open API 3.0 specification

SpringDoc

SpringDoc is also a project (unofficial) maintained by the spring community to help users integrate swagger3 into Spring.
It is also used to help developers generate documentation in Spring and can be easily used in spring boot.

The projects under this organization support swagger page Oauth2 login (the content of Open API3). Compared with SpringFox, it has a longer support time and is undoubtedly a better choice. However, due to the slow development in China, it is not easy to see too many useful documents in China, but you can visit its official website . It uses swagger3 (OpenAPI3), but swagger3 is not compatible with swagger2’s annotations and is not easy to migrate. Therefore, it is not as famous as spring fox.

Migrate from spring-fox to springdoc

Dependency changes

Remove the dependencies of springfox or swagger in pom.xml. add springdoc-openapi-ui.

<dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.3.1</version>
   </dependency>

Use swagger3 annotations instead of swagger2’s (optional)

This step is optional, because the changes are too large, so springfox has made compatibility with the old version of swagger.
But I don’t know if it will be incompatible in the future. Here is how to use swagger 3 annotations (already introduced above) to replace swagger 2’s
( note that the package path for modifying swagger 3 annotations is io.swagger.v3.oas.annotations.)

The corresponding relationship is:

Swagger2’s annotation naming is based on ease of use, and all start with Api. After cultivating the habit of users to rely on annotations, Swagger 3 standardizes and engineering the annotation names.

Modify Api grouping (if and only if you have previously defined multiple Docket Beans)

Old:

@Bean
    public Docket publicApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
                .paths(PathSelectors.regex("/public.*"))
                .build()
                .groupName("springshop-public")
                .apiInfo(apiInfo());
    }

    @Bean
    public Docket adminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
                .paths(PathSelectors.regex("/admin.*"))
                .build()
                .groupName("springshop-admin")
                .apiInfo(apiInfo());
    }

new:

@Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .setGroup("springshop-public")
                .pathsToMatch("/public/**")
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .setGroup("springshop-admin")
                .pathsToMatch("/admin/**")
                .build();
    }

If there was only one Docket before, delete it and replace it with the configuration file

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

Other cases

swagger ui is behind a proxy like nginx

See this
https://springdoc.org/faq.html#how-can-i-deploy-the-doploy-springdoc-openapi-ui-behind-a-reverse-proxy.

Customize Swagger UI

https://springdoc.org/faq.html#how-can-i-configure-swagger-ui.

Hide an interface or Controller from the document

https://springdoc.org/faq.html#how-can-i-hide-an-operation-or-a-controller-from-documentation-.

Leave a Comment

Your email address will not be published. Required fields are marked *