项目引入knife4j(swagger2)记录

前言

先说说背景吧。这次改造是公司的项目。之前我们使用的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的引入不一样,没有那么多注意事项。


    com.github.xiaoymin
    knife4j-spring-boot-starter
    2.0.2

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

配置

配置大体上分为两部分:

  • 基本设置,以让框架生效,这包括了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")

你可能感兴趣的:(项目引入knife4j(swagger2)记录)