SpringBoot interface - how to generate the Swagger technology stack of interface documentation?

SpringBoot develops Restful interface, is there any API specification? How to quickly generate API documentation? Swagger is a web service for generating, describing, and invoking RESTful interfaces. In layman's terms, Swagger is a service that displays all (wanted to expose) interfaces in the project on the page, and can perform interface calls and tests. This article mainly introduces the OpenAPI specification and the integration scheme of the Swagger technology stack based on the OpenAPI specification. @pdai

• SpringBoot interface - how to generate the Swagger technology stack of interface documentation?

  • Prepare knowledge points

    • What is the OpenAPI Specification (AOS)?
    • What is Swagger?
    • What is the relationship between Swagger and SpringFox?
    • What is Knife4J? How does it relate to Swagger?

  • Implementation case of Swagger3

    • POM
    • Swagger Config
    • controller interface
    • run the test

  • Implementation case of Knife4J

    • POM
    • yml configuration
    • inject configuration
    • Controller interface
    • run the test
  • Sample source code
  • more content

Prepare knowledge points

Before generating documentation, you need to understand the relationship between OpenAPI specification, Swagger, SpringFox, Knife4J, Swagger UI, etc. @pdai

What is the OpenAPI Specification (AOS)?

The OpenAPI Specification (OAS) defines a standard, language-agnostic RESTful API interface specification that allows both developers and operating systems to view and understand the functionality of a service without access to source code, documentation, or network traffic inspection (either It is convenient for humans to learn and read, and it is also convenient for machines to read). When OAS is properly defined, developers can understand and interact with remote services with minimal implementation logic.

In addition, documentation generation tools can use the OpenAPI specification to generate API documentation, and code generation tools can generate server and client code, test code, and other use cases in various programming languages.

Official GitHub address: OpenAPI-Specification

What is Swagger?

Swagger is a web service for generating, describing, and invoking RESTful interfaces. In layman's terms, Swagger is a service that displays all (wanted to expose) interfaces in the project on the page, and can perform interface calls and tests.

From the above Swagger definition, it is not difficult to see that Swagger has the following three important functions:

• Display all interfaces in the project on the page, so that back-end programmers do not need to write special interface documents for front-end users;
• When the interface is updated, it is only necessary to modify the Swagger description in the code to generate a new interface document in real time, thus avoiding the problem that the interface document is old and cannot be used;
• Through the Swagger page, we can directly call the interface, which reduces the debugging cost in the project development stage.

Swagger3 fully complies with the OpenAPI specification. Swagger official website address: https://swagger.io/ .

What is the relationship between Swagger and SpringFox?

Swagger can be seen as a technology that follows the OpenAPI specification, and springfox is the specific implementation of this technology. Just like AOP and DI in Spring, the former is the idea and the latter is the implementation.

What is Knife4J? How does it relate to Swagger?

The essence is an enhanced solution of Swagger, the predecessor is just a SwaggerUI (swagger-bootstrap-ui)

Knife4j is an enhanced solution for the Java MVC framework to integrate Swagger to generate Api documents. The predecessor is swagger-bootstrap-ui. The name kni4j is to hope that it can be as small, light and powerful as a dagger!

The predecessor of Knife4j is swagger-bootstrap-ui. In order to meet the development of microservice architecture, because the original swagger-bootstrap-ui adopts the mixed packaging method of back-end Java code + front-end Ui, it is very bloated under the microservice architecture. So the project was officially renamed knife4j

Main areas of focus after the name change

• The front-end and back-end Java code and the front-end Ui module are separated, making it more flexible to use under the microservice architecture
• Provide an enhanced solution focused on Swagger , different from just improving the front-end UI part

For related documents, please refer to: https://doc.xiaominfo.com/knife4j/documentation/

Implementation case of Swagger3

Let's first look at how the latest Swagger3 configures and implements the interface.

POM

According to the above introduction, we introduced the springfox dependency package, the latest version is 3.xx. Compared with the previous version, you only need to introduce the following starter package.

 <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Swagger Config

We also added some global configurations in the configuration, such as global parameters, etc.

 package tech.pdai.springboot.swagger.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import tech.pdai.springboot.swagger.constant.ResponseStatus;

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;

/**
 * swagger config for open api.
 *
 * @author pdai
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    /**
     * @return swagger config
     */
    @Bean
    public Docket openApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("Test group")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponse());
    }

    /**
     * @return global response code->description
     */
    private List<Response> getGlobalResponse() {
        return ResponseStatus.HTTP_STATUS_ALL.stream().map(
                a -> new ResponseBuilder().code(a.getResponseCode()).description(a.getDescription()).build())
                .collect(Collectors.toList());
    }

    /**
     * @return global request parameters
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("AppKey")
                .description("App Key")
                .required(false)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }

    /**
     * @return api info
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger API")
                .description("test api")
                .contact(new Contact("pdai", "http://pdai.tech", "[e-mail]"))
                .termsOfServiceUrl("http://xxxxxx.com/")
                .version("1.0")
                .build();
    }
}

controller interface

 package tech.pdai.springboot.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import tech.pdai.springboot.swagger.entity.param.UserParam;
import tech.pdai.springboot.swagger.entity.vo.AddressVo;
import tech.pdai.springboot.swagger.entity.vo.UserVo;

import java.util.Collections;
import java.util.List;

/**
 * @author pdai
 */
@Api
@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * http://localhost:8080/user/add .
     *
     * @param userParam user param
     * @return user
     */
    @ApiOperation("Add User")
    @PostMapping("add")
    @ApiImplicitParam(name = "userParam", type = "body", dataTypeClass = UserParam.class, required = true)
    public ResponseEntity<String> add(@RequestBody UserParam userParam) {
        return ResponseEntity.ok("success");
    }

    /**
     * http://localhost:8080/user/list .
     *
     * @return user list
     */
    @ApiOperation("Query User List")
    @GetMapping("list")
    public ResponseEntity<List<UserVo>> list() {
        List<UserVo> userVoList = Collections.singletonList(UserVo.builder().name("dai").age(18)
                .address(AddressVo.builder().city("SZ").zipcode("10001").build()).build());
        return ResponseEntity.ok(userVoList);
    }
}

run the test

Open the Documentation API webpage

Test adding a user

Query user list

Implementation case of Knife4J

Here is the best implementation of using Java to generate interface documentation: SwaggerV3 (OpenAPI) + Knife4J.

POM

 <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

yml configuration

 server:
  port: 8080
knife4j:
  enable: true
  documents:
    - group: Test Group
      name: My Documents
      locations: classpath:wiki/*
  setting:
    # default lang
    language: en-US
    # footer
    enableFooter: false
    enableFooterCustom: true
    footerCustomContent: MIT | [Java 全栈](https://pdai.tech)
    # header
    enableHomeCustom: true
    homeCustomLocation: classpath:wiki/README.md
    # models
    enableSwaggerModels: true
    swaggerModelName: My Models

inject configuration

 package tech.pdai.springboot.knife4j.config;

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import tech.pdai.springboot.knife4j.constant.ResponseStatus;

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;

/**
 * swagger config for open api.
 *
 * @author pdai
 */
@Configuration
@EnableOpenApi
public class OpenApiConfig {

    /**
     * open api extension by knife4j.
     */
    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public OpenApiConfig(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    /**
     * @return swagger config
     */
    @Bean
    public Docket openApi() {
        String groupName = "Test Group";
        return new Docket(DocumentationType.OAS_30)
                .groupName(groupName)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponse())
                .extensions(openApiExtensionResolver.buildExtensions(groupName))
                .extensions(openApiExtensionResolver.buildSettingExtensions());
    }

    /**
     * @return global response code->description
     */
    private List<Response> getGlobalResponse() {
        return ResponseStatus.HTTP_STATUS_ALL.stream().map(
                a -> new ResponseBuilder().code(a.getResponseCode()).description(a.getDescription()).build())
                .collect(Collectors.toList());
    }

    /**
     * @return global request parameters
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("AppKey")
                .description("App Key")
                .required(false)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }

    /**
     * @return api info
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("test api")
                .contact(new Contact("pdai", "http://pdai.tech", "[e-mail]"))
                .termsOfServiceUrl("http://xxxxxx.com/")
                .version("1.0")
                .build();
    }
}

Where ResponseStatus encapsulates

 package tech.pdai.springboot.knife4j.constant;

import lombok.AllArgsConstructor;
import lombok.Getter;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;

/**
 * @author pdai
 */
@Getter
@AllArgsConstructor
public enum ResponseStatus {

    SUCCESS("200", "success"),
    FAIL("500", "failed"),

    HTTP_STATUS_200("200", "ok"),
    HTTP_STATUS_400("400", "request error"),
    HTTP_STATUS_401("401", "no authentication"),
    HTTP_STATUS_403("403", "no authorities"),
    HTTP_STATUS_500("500", "server error");

    public static final List<ResponseStatus> HTTP_STATUS_ALL = Collections.unmodifiableList(
            Arrays.asList(HTTP_STATUS_200, HTTP_STATUS_400, HTTP_STATUS_401, HTTP_STATUS_403, HTTP_STATUS_500
            ));

    /**
     * response code
     */
    private final String responseCode;

    /**
     * description.
     */
    private final String description;

}

Controller interface

 package tech.pdai.springboot.knife4j.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import tech.pdai.springboot.knife4j.entity.param.AddressParam;

/**
 * Address controller test demo.
 *
 * @author pdai
 */
@Api(value = "Address Interfaces", tags = "Address Interfaces")
@RestController
@RequestMapping("/address")
public class AddressController {
    /**
     * http://localhost:8080/address/add .
     *
     * @param addressParam param
     * @return address
     */
    @ApiOperation("Add Address")
    @PostMapping("add")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "city", type = "query", dataTypeClass = String.class, required = true),
            @ApiImplicitParam(name = "zipcode", type = "query", dataTypeClass = String.class, required = true)
    })
    public ResponseEntity<String> add(AddressParam addressParam) {
        return ResponseEntity.ok("success");
    }

}

run the test

Custom User Homepage

model

Global parameters and configuration

custom document

Interface Documentation and Test Interfaces

Sample source code

Other older implementations:

• swagger2
• Swagger2+BootstrapUI
• Knife4j v2

More examples can be found in the following repositories

https://github.com/realpdai/tech-pdai-spring-demos

more content

Say goodbye to fragmented learning, one-stop systematic learning without routines Back-end development: Java full stack knowledge system (https://pdai.tech)