微服务系列之SpringBoot基础：集成knife4j文档组件

SpringBoot集成knife4j文档组件

---

前言

在实际项目开发中，基本都是采用前后端分离开发，需要由前后端共同定义接口，编写接口文档，之后根据接口文档进行开发，且需要经常人工维护。在线接口文档使得项目开发过程中前后端工程师有一个统一的文档进行沟通交流，项目维护中人员更迭，都能及时的方便项目人员查看、维护。

---

一、引入 maven 依赖

 <!--api wiki文档组件-->
 <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>knife4j-spring-boot-starter</artifactId>
      <version>3.0.2</version>
 </dependency>

二、配置类、Controller和JavaBean类

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {

    @Bean
    public Docket defaultAllApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfoWebBack())
                .select()
                .apis(requestHandler -> requestHandler.isAnnotatedWith(ApiOperation.class))  //注解写法
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getDefaultParameterList());//可选
    }
    /**
     * admin 分组
     *
     * @return
     */
    @Bean(value = "adminApi")
    public Docket adminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("后台API分组")
                .apiInfo(apiInfoWebBack())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.admin")) //平常写法
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfoWebBack() {
        Contact contact = new Contact("huanghong", "", "xdhong@qq.com");
        return new ApiInfoBuilder()
                .title("xxx-api接口")
                .description(C.codeStr)
                .contact(contact)
                .version("1.0")
                .build();
    }

    private List<RequestParameter> getDefaultParameterList() {
        List<RequestParameter> parameterList = new ArrayList<>();
        RequestParameterBuilder appkeyBuilder = new RequestParameterBuilder();
        appkeyBuilder.name(C.API_HEADER_PARAM_APPKEY)
                .query(q -> q.defaultValue("1").model(modelSpecificationBuilder -> modelSpecificationBuilder.scalarModel(ScalarType.STRING)))
                .description("appkey")
                .in("header")
                .required(true)
                .build();
        parameterList.add(appkeyBuilder.build());

        RequestParameterBuilder timestampBuilder = new RequestParameterBuilder();
        timestampBuilder.name(C.API_HEADER_PARAM_TIMESTAMP)
                .query(q -> q.defaultValue("111111111111").model(modelSpecificationBuilder -> modelSpecificationBuilder.scalarModel(ScalarType.STRING)))
                .description("timestamp")
                .in("header")
                .required(true)
                .build();
        parameterList.add(timestampBuilder.build());

        RequestParameterBuilder signBuilder = new RequestParameterBuilder();
        signBuilder.name(C.API_HEADER_PARAM_SIGN)
                .query(q -> q.defaultValue("1").model(modelSpecificationBuilder -> modelSpecificationBuilder.scalarModel(ScalarType.STRING)))
                .description("sign")
                .in("header")
                .required(true)
                .build();
        parameterList.add(signBuilder.build());

        RequestParameterBuilder sessionBuilder = new RequestParameterBuilder();
        sessionBuilder.name(C.API_HEADER_PARAM_SESSION)
                .query(q -> q.defaultValue("111111111111111111111111111111111").model(modelSpecificationBuilder -> modelSpecificationBuilder.scalarModel(ScalarType.STRING)))
                .description("session")
                .in("header")
                .required(true)
                .build();
        parameterList.add(sessionBuilder.build());

        return parameterList;
    }
}

@RestController
@Api(value = "接口名称", tags = "说明")
@RequestMapping("/api/v1")
@Slf4j
@RefreshScope
public class PassController {
 
    @GetMapping(value = "/list")
    @ApiOperation("列表页面")
    public TResult<PageObject<FjPassHeadVO>> list(
            @ApiParam(required = false, value = "组织id") @RequestParam(required = false) String phidOrg,
            @ApiParam(required = false, value = "项目id") @RequestParam(required = false) String phidProject,
            @ApiParam(required = false, value = "分公司id") @RequestParam(required = false) String phidArea,
            @ApiParam(required = false, value = "单据开始日期") @RequestParam(required = false) String checkStartTime,
            @ApiParam(required = false, value = "单据截止日期") @RequestParam(required = false) String checkEndTime,
            @ApiParam(required = true, value = "当前页码") @RequestParam(required = true) Integer page,
            @ApiParam(required = true, value = "每页条数") @RequestParam(required = true) Integer size,
            HttpServletRequest request) throws ParseException {
         }
    }

@ApiModel("单据表头")
@Data
public class PassHeadVO implements Serializable {

    @ApiModelProperty(value="主键id-修改必传")
    private String phid;
    
    @ApiModelProperty(value="单据编码")
    private String billcode;    
    
    @ApiModelProperty(value="单据日期",required = true)
    @NotNull(message = "单据日期不能为空")
    private Date billdate;
    
    @ApiModelProperty(value="申请人id",required = true)
    @NotBlank(message = "申请人id不能为空")
    private String phidApplyman;
}

三、界面效果

swagger 默认访问地址是：http://{host}:{port}/doc.html

四、主要注解说明

（一）@Api
表示这个类是Swagger的资源，该注解会被Swagger扫描到，该注解可以自定义显示的导航栏标签的名称tag；

（二）@ApiOperation
用在方法上，说明方法的作用
@ApiOperation注解中的tags属性做更细粒度的接口分类定义，该注解可以用于多个不同的controller的分组（即在另外的controller中定义的接口方法是可以分属到其他的接口tag下）；

（三）@ApiIgnore
忽略掉指定的接口和类，在开发中肯定存在一些用于跳转路由的controller，那么其实这部分是不需要把接口呈现给其他开发人员的，所以就可以通过@ApiIgnore注解忽略掉该注解；

（四）@ApiParam
以作用在接口方法上面，以及接口方法中的参数位置的注解，其主要是用来给接口中的参数定义相关参数说明，主要是为了，帮助相关人员理解接口中每个参数的含义；

（五）@ApiModel
ApiModel 注解是作用在接口相关实体类上的注解，用来对该接口相关实体类添加额外的描述信息，常常和 @ApiModelProperty 注解配合使用；

（六）@ApiModelProperty
ApiModelProperty 注解是作用在接口相关实体类的参数上的注解，用来对具体的接口相关实体类中的参数添加额外的描述信息，常常和 @ApiModel 注解关联使用；

---