Use of Knife4j online API documentation framework in SpringBoot

Table of contents

1. About Knife4j

2. Basic use

3. Detailed configuration

1. About Knife4j

Knife4j is an online API documentation framework based on Swagger 2.

2. Basic use

2.1 Add dependencies to the project

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

(Note) The above dependencies are only applicable to versions before Spring Boot 2.6 (not included).

2.2  Enable enhanced mode in the configuration file

Add in application.properties:

knife4j.enable=true

2.3 Custom configuration class

Create Knife4jConfiguration.class under the config folder of the project (the configuration class created by yourself to store the project), and add the configuration:

Configuration code is relatively fixed

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

   
    //指定Controller包路径
    private String basePackage = "com.example.demo.controller";
    
    //分组名称
    private String groupName = "product";
    
    //主机名
    private String host = "http://localhost";
    
    //标题
    private String title = "Demo在线API文档";
    
    //简介
    private String description = "Demo在线API文档";

    //服务条款URL
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    
    //联系人
    private String contactName = "xxx";
    
    //联系网址
    private String contactUrl = "http://localhost";
    
    //联系邮箱
    private String contactEmail = "[email protected]";
    
    //版本号
    private String version = "1.0.0";

    @Autowired
    private OpenApiExtensionResolver openApiExtensionResolver;

    @Bean
    public Docket docket() {
        String groupName = "1.0.0";
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .host(host)
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(new Contact(contactName, contactUrl, contactEmail))
                .version(version)
                .build();
    }

}

2.4 Access

Open the browser and enter http://localhost:8080/doc.html to access. (use the address and interface configured by the project)

3. Detailed configuration

1) Add the `@Api annotation to the controller class , configure the `tags` attribute , and specify the module name (the name displayed in the first-level menu in the API document

2) Add the @ApiOperation annotation to the method of processing the request , configure the value attribute, and specify the business name (the name displayed by the subitem of the first-level menu in the API document)

3) Add the @ApiOperationSupport` annotation to the method of processing the request , configure the `order` attribute , and the value is a value, you can specify the display sort number of the business, and it will be arranged in ascending order according to the value of the order attribute

example:

@Api(tags = "轮播图管理模块")
@RestController
@RequestMapping("/banners")
public class BannerController {
    @Autowired
    private IBannerService iBannerService;
   
    @ApiOperation("添加轮播图")
    @ApiOperationSupport(order=101)
    @PostMapping("/addBanner")
    public JsonResult addNewBanner(@RequestBody BannerDTO bannerDto){
        iBannerService.addNewBanner(bannerDto);
        return JsonResult.ok();
    }
}

 4) Add the @ApiModelProperty annotation to the attribute of the POJO parameter of the method that processes the request , configure the value attribute , and specify the description of the parameter. In addition, you can also configure whether this parameter is required through the required attribute of the annotation (it does not have the checking function, It's just shown on the API docs as a mandatory submission)

@Data
public class BannerDTO implements Serializable { 

    @ApiModelProperty(value="图片地址",required = true,example ="xxx")
    private String imgUrl;
}