Knife4j, with SpringBoot use is perfect!

preface

API document connection is an essential link in the era of front-end and back-end separation. In order to greatly improve efficiency, a concise, easy-to-use and beautiful document is of great importance. Initially, the API document was a purely hand-written Word. However, programmers are a group of highly automated and efficient people. Hence the birth of fully automated online documentation that starts with code, most notably Swagger. Swagger is efficient, but it also has disadvantages. Knife4j encapsulates Swagger, including but not limited to parameter ignoring, offline (MD, HTML, DOC, JSON) documents, etc. It satisfies and exceeds the self-cultivation of an API document.

About knife4j

Knife4j website:

doc.xiaominfo.com/knife4j/

There are two major versions 3.x and 2.x, officially explained as follows

The latest version is 3.0.2.

Interface appreciation

Hands-on practice

The sample version

1. Introduce dependencies

<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> The < version > 3.0.2 < / version > < / dependency >Copy the code

Swagger configuration class knife4J

If you’ve used or are using Swagger as your API documentation, this code should be familiar, because it doesn’t make any difference.

@Configuration public class SwaggerConfig { @Bean public Docket docket() { return new Docket(DocumentationType.OAS_30) .apiinfo (apiInfo()).select() // Control package name, Automatically scan all the interfaces in the package. The apis (RequestHandlerSelectors. BasePackage (" org. Programlife2016. Knife4j. Web ")). The paths (PathSelectors. Any ()) .build(); } private ApiInfo ApiInfo () {return new ApiInfoBuilder() // document.title ("knife4j") // Document description .description(" knife4J sample document ") // Your contact information. Contact(new contact("ProgramLife2016", "XXX ", "XXX ")) // document version.version ("1.0").build(); }}Copy the code

3. Entity classes

@getter@setter@toString Public class UserModel {@apiModelProperty (" primary key ") private Integer ID; @APIModelProperty (" name ") private String name; @APIModelProperty (" age ") private Integer age; }Copy the code

As you can see, the @APIModelProperty annotation is used instead of the traditional Java annotation. Knife4j will read the value of the annotation and display it as a parameter description in the document so that the docking point can clearly understand the attribute represented by the field.

4. Control layer

@API (tags = "user module ") @restController @RequestMapping("/user") Public Class UserController {@autoWired private UserService userService; @apiOperation (" add") @postmapping ("/add") public result <UserModel> add(@requestBody UserModel UserModel) { userService.add(userModel); return CommonResult.success(); } @apiOperation (" update") @putMapping ("/update") public result <UserModel> update(@requestBody UserModel UserModel) { userService.update(userModel); return CommonResult.success(); }}Copy the code

Two annotations @api and @apiOperation are used here.

At sign Api is a description of the whole class,

@apiOperation is a description of a single interface.

Visit knife4J to view and debug the interface

After starting the SpringBoot service, a browser visiting Knife4J will see the renderings in ‘Interface appreciation’ at the address of

http://127.0.0.1:8080/doc.html

Knife4j common features

Knife4j has a number of enhancements to Swagger, here are a few of the most common.

To use the enhanced features, you need to enable them in application.yml

knife4j:
  enable: true
Copy the code

Filter request parameters

In addition interface, sometimes we use the same model for convenience (in fact, lazy), but there is no need to pass the ID in the new interface, and it is mandatory to pass the ID in the modification interface. If this field is displayed in the API document, it will be confusing. In this case, filtering request parameters is particularly important. In KNIfe4J, all you need is an @apiOperationSupport annotation.

@apiOperation (" add") @apiOperationSupport (ignoreParameters = {"id"}) @postMapping ("/add") public CommonResult<UserModel> add(@RequestBody UserModel userModel) { userService.add(userModel); return CommonResult.success(); }Copy the code

Global parameters

Knife4j supports both query (form) and Header (request header). Just set it in the sidebar ‘Document Management -> Global Parameter Settings’.

Offline files

Knife4j supports exporting offline documents in four formats (MD, HTML, DOC, JSON) in the sidebar ‘Document Management -> Offline Documents’.

Md Export effect diagram

Knife4j support for microservices architecture

Knife4j supports microservice architectures, which are increasingly popular with Internet giants. Limited to the length of the article, the official document is also written in detail, here stop here, no further details, friends in need please move to the official document

Doc.xiaominfo.com/knife4j/act…