How to form standard interface documents

One 、 demand

When the front and rear ends are butted , The backend needs to provide a standard , In other words, it is very important for the front end to understand the interface documents . How to use annotations quickly 、 Simply form interface documents .

Two 、Swagger2 Switch knife4j Use

1、 stay pom.xml add knife4j Related dependence of

<!-- Integrate Knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>

2、 stay Swagger2Config Add one @EnableKnife4j annotation , This annotation can open knife4j Enhancements for  

@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {

    @Bean
    public Docket ssoFront() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(" Package path of the interface "))
                .paths(PathSelectors.any())
                .build().groupName(" Group name ");
    }

    @Bean
    public Docket ssoAdmin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.user.controller.admin"))
                .paths(PathSelectors.any())
                .build().groupName("sso-admin");
    }

    @Bean
    public Docket member() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.user.controller.member"))
                .paths(PathSelectors.any())
                .build().groupName("member-service");
    }

    @Bean
    public Docket system() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.user.controller.system"))
                .paths(PathSelectors.any())
                .build().groupName("system-service");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(" Module documentation ")
                .description(" User module API file ")
                .contact(new Contact(" author ", null, null))
                .version("v1")
                .build();
    }

}

3、 Run our SpringBoot application , visit API The document address can be viewed ：http://localhost: Port number /doc.html

3、 ... and 、 Functional characteristics

contrast swagger Come on

1、 The returned result set supports folding , Convenient view

2、 The request parameters are JSON Check function

3、 knife4j Support the export of offline documents , Easy to send to others , Support Markdown Format ; Direct selection Document management -> Offline documents function , And then choose download Markdown that will do

3、 ... and 、 Use different annotations to form interface documents according to different request methods

One 、swagger Annotation application

1、 In the control layer , Can be in controller Use notes on @Api(tags = " Interface service name ") Mark the function of this controller .

2、 Annotations can be used on specific interfaces @ApiOperation(value = " Mailbox fuzzy matching query service interface ",notes = " Fuzzy matching of mailboxes ") Name the interface and describe the functions of the interface

  Two 、@ApiOperation And Get Request annotations to use with

1、 Using annotations @RequestParam(value = " Incoming email ",required = false), Be careful name and value Can't coexist , Otherwise, the interface document cannot be generated .swagger It will automatically recognize this annotation and generate the corresponding document

 Get The request data type is ：

2、 Use  @PathVariable(value = " Incoming email ",required = false) It's the same thing . The only difference is that the request type is different query, One is path

3、 Unwanted @ApiImplicitParam(name = " Mailbox fuzzy matching query ", value = "likeEmail", required = false) This annotation , Otherwise, two same parameters will appear .

3、 ... and 、@ApiOperation And Post Request annotations to use with

1、 Use @RequestBody Annotation request parameter entity . In the entity, add

@ApiModel(value = " XX request message ",description = " XX request message , The parent class is ",parent =  class .class)

2、 Add

@ApiModelProperty(value=" So and so attribute ",required = true)

    @ApiOperation(" XX request message ")
    @PostMapping("edit")
    public JsonResult edit(@RequestBody EditDTO dto) {
        return 
    }

swagger It will automatically scan the annotated data in the entity class to form the interface document

3、post Request data format

Four 、 All return messages with return parameters need to specify the return parameters

Only with a clear return message , And in the message   Class name @ApiModel And attribute @ApiModelProperty Notes are also used , Then the data type of the returned message will also appear in the interface document .

  Corresponding examples will also appear below 、

notes ： For the combination of annotations and request types, please refer to the following article

POST、GET、@RequestBody and @RequestParam difference _Archie_java The blog of -CSDN Blog