前言

先说说背景吧。这次改造是公司的项目。之前我们使用的showdoc进行接口文档管理的。说实话，效果不错。但是，问题是时间长了之后，接口文档会和实现脱节从而无法信任接口文档。这个问题其实我知道，但是，可能是体会少吧。由于从理想的角度来说，希望先出接口文档再进行编码，所以就拒绝使用swagger这种嵌入在代码里的接口文档维护方式。现在想来，还是太过理想化了。其实，如果真的要先出文档再编码，也可以借助写文档的过程把空接口写出来。另外，由于我想明白了怎么用git实现研发流程（https://www.jianshu.com/p/1bf5b3c6f1c8
），和现有产线的冲突问题也就不存在了。
再说说，为什么是knife4j而不是单纯的swagger2。这个决策，其实没那么严谨。多数原因是机缘巧合吧。在前段时间，我折腾怎么管理springcloud的文档的时候，想要在gateway一个地方看到所有接口的文档，折腾的时候找到的knife4j(https://www.jianshu.com/p/ce56e783d40f
) 。后来发现，这个框架也不是专门为了解决springcloud集成而诞生的，它是一个swagger的ui美化项目，核心还是swagger，改了改界面。那就用它吧。反正，配置也挺透明的，实在不行，改个依赖也就改回去了。

依赖

这里的依赖，和gateway的引入不一样，没有那么多注意事项。

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

如上即可，版本自己改成合适的就行了。我选了个最新的。

配置

配置大体上分为两部分：

• 基本设置，以让框架生效，这包括了knife4j和swagger两部分。虽然是两部分，这里一并配置就可以了，很简单。
• 会话设置。如果应用系统是需要登录才能访问各个接口的话，那它访问swagger的接口也是需要登录的，很不方便，这里我们就想办法去掉它。

基本配置

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
    @Bean
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName("默认版本API")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.ym"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("资源统一管理平台API")
                .description("资源统一管理平台提供的所有API")
                .version("1.0")
                .build();
    }
}

上面就是我基本配置的全部代码。可以看到defaultApi2方法才是真正的注册bean的方法。而这个bean最主要的其实就是配置了扫描的基础包路径，至于apiinfo，那是页面显示的东西，没多少实际用途。另外，最主要的要看到上面的三个注解。@EnableSwagger2、@EnableKnife4j这两个就不解释了，看名字就知道。@Import(BeanValidatorPluginsConfiguration.class)最后这个，说实话，我没查，也不知道是干什么的，反正能运行了，回头再说吧。

会话配置

我这个系统的api是有session的，所有接口会验证其携带的sessionToken。所以，需要对相关的接口进行排除。官方说明的有下面这些：

/swagger-resources:Swagger的分组接口
/v2/api-docs?group=groupName:Swagger的具体分组实例接口,返回该分组下所有接口相关的Swagger信息
/v2/api-docs-ext?group=groupName:该接口是SwaggerBootstrapUi提供的增强接口地址,如不使用UI增强,则可以忽略该接口
/doc.html:接口界面url

具体排除我就不写了，各应用使用的方法不同，需要的代码也不同。总之，排除之后，访问/doc.html，就可以看到接口文档了。它应该是扫描了所有的controller注解，生成的。所以，没有特意写过的接口也可看到。

文档配置

文档配置的内容说来也很简单。在类上标注ApiModel，在属性上标注ApiModelProperty。这两个注解可以帮助你控制在文档中展示的内容。主要就是写value。我还用到了required属性。其它的，有需要的时候再研究吧。下面给两个样例吧：

@ApiModel(value="创建KeyValue请求对象")

@ApiModelProperty(value = "排序号.数值越大越靠前。取值范围1~1000")