Java's operation steps to optimize Swagger interface documents using Knife4j

Preface

In modern microservice development, the quality of interface documents directly affects the front-end and back-end collaboration efficiency. As a mainstream interface documentation tool, Swagger is powerful, but its default interface and some functions are slightly insufficient in actual use. And the advent of Knife4j provides us with an enhanced option. Based on Swagger, it adds a more friendly user interface and practical functions, making interface documents more intuitive and efficient. This article will provide a detailed introduction to how to integrate and use Knife4j in a project, while also exploring its best practices in real-world development.

1. Introduction to Knife4j and core functions

Knife4j is an open source enhancement tool based on Swagger, with its core goal being to optimize the usability and user experience of interface documents. Compared to native Swagger UI, Knife4j provides the following main features:

1.1 More friendly interface

Knife4j provides a more modern and easier-to-use user interface, supports grouping, interface search, sorting and other functions, significantly improving the operational efficiency of developers and testers.

1.2 Enhanced documentation support

Knife4j supports richer annotations, such as parameter descriptions, request examples, response examples, etc., making the interface document more readable and practical.

1.3 Multi-environment support

Through simple configuration, Knife4j can support the display of multi-environment documents, which facilitates developers to quickly verify interfaces in different environments.

2. Integrate Knife4j in the project

Here are the specific steps to optimize interface documentation using Knife4j:

2.1 Introducing Knife4j dependencies

On the projectAdd the Maven coordinates of Knife4j to the file:

<dependency>
    <groupId></groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version></version>
</dependency>

Among them, please select the specific version according to the project needs.

2.2 Configuring the Swagger path

Knife4j inherits Swagger's configuration by default, so you need to configure the basic path of Swagger in or. Here is a simple configuration example:

spring:
  application:
    name: demo-application

knife4j:
  enable: true
  group-name: Default grouping

swagger:
  api-docs:
    path: /v3/api-docs
  base-package:

In the above configuration,Used to open the Knife4j interface,-packageUse to specify the path of the scanned controller package.

2.3 Enable Knife4j's front-end page

Knife4j provides enhanced document pages with the default path:http://localhost:8080/swagger/. Simply access the path in your browser to view the optimized document interface.

3. Use annotations to improve document quality

In order to make the interface document clearer and more comprehensive, it is necessary to use annotations in the code to annotate interfaces and parameters.

3.1 Add @API annotation in Controller

@APIAnnotations are used to add overall description information to the controller. Examples are as follows:

@RestController
@RequestMapping("/api/user")
@Api(tags = "User Management Interface")
public class UserController {
    // Specific methods}

3.2 Add @ApiOperation annotation to the method

@ApiOperationAnnotations are used to describe the functions of interface methods:

@GetMapping("/info/{id}")
@ApiOperation(value = "Get user information based on ID", notes = "Need to provide a unique identity ID for the user")
public ResponseEntity&lt;User&gt; getUserById(@PathVariable Long id) {
    // Method implementation}

3.3 Add @ApiParam annotation to the parameters

For the parameters of the method,@ApiParamAnnotations can be used for additional explanations:

@GetMapping("/search")
@ApiOperation(value = "Query User")
public ResponseEntity&lt;List&lt;User&gt;&gt; searchUsers(
    @ApiParam(value = "username", required = false) @RequestParam String username,
    @ApiParam(value = "page number", required = true) @RequestParam int page
) {
    // Method implementation}

3.4 Add @ApiModel annotation to the entity class

Entity class can be passed@ApiModelAnnotation adds description information to the overall:

@ApiModel(description = "User Entity")
public class User {
    // Attributes}

3.5 Add @ApiModelProperty annotation to entity class properties

@ApiModelPropertyAnnotations are used to describe the field of entity class:

@ApiModelProperty(value = "User Unique Identity")
private Long id;

@ApiModelProperty(value = "username", required = true)
private String username;

4. Avoid FAQs

There are some precautions to keep in mind when using Knife4j:

4.1 HashMap Incompatibility Issues

The return value of Knife4j isHashMapThe interface is unfriendly, which will cause the return structure to be not displayed correctly in the interface document. It is recommended to use a custom return value type instead:

@ApiModel(description = "General Response Entity")
public class ApiResponse&lt;T&gt; {
    @ApiModelProperty(value = "Response Status Code")
    private int code;

    @ApiModelProperty(value = "Response Message")
    private String message;

    @ApiModelProperty(value = "data")
    private T data;

    // Getter and Setter}

Through the above definition, the interface return value can more clearly show its structure:

@GetMapping("/info/{id}")
@ApiOperation(value = "Get user information")
public ApiResponse&lt;User&gt; getUserInfo(@PathVariable Long id) {
    // Method implementation}

4.2 Missing annotation problem

If the relevant annotations are not added correctly, Knife4j will not be able to fully display the interface documentation. Therefore, during the development process, it is necessary to develop good habits and label each interface and parameters in detail.

5. Extension and optimization of Knife4j

In addition to basic functions, Knife4j also supports a variety of expansion capabilities, such as interface grouping, dynamic parameter setting, etc.

5.1 Interface Grouping

pass@ApiAnnotatedtagsAttributes, interface grouping can be easily implemented:

@Api(tags = "Order Management Interface")
@RestController
@RequestMapping("/api/order")
public class OrderController {
    // Order-related methods}

5.2 Dynamic parameters

Knife4j provides the display function of dynamic request parameters, suitable for interfaces with complex query conditions.

Conclusion

The integration and use of Knife4j makes the interface documents more intuitive and friendly, providing great convenience for developers and testers. In actual projects, in addition to following best practices, functional expansion can also be performed according to business needs to bring the quality of interface documents to a higher level.

The above is the detailed operation steps for Java to optimize Swagger interface documents using Knife4j. For more information about Java Knife4j optimization of Swagger documents, please pay attention to my other related articles!