Swagger在线文档之knife4j实战讲解 - HelloWorld开发者社区

一、背景

目前Swagger在线文档官方的UI页面美感、操作舒适度难以满足开发、测试等相关人员；经过调研后，发现了knife4j这款文档插件非常漂亮,且插件社区成熟度也相对比较高，博主在此为各位小伙伴作个分享。

二、knife4j简介

knife4j是一个通过基于Swagger二次开发来增强Swagger UI以及其它一些用户急需功能的一个在线文档解决方案；它支持自定义文档[.md]，以及对接口功能进行分组和排序等新特性**[由于新特性比较多，这里就不一一列举]**；

三、knife4j使用[springboot]

1.pom.xml添加
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-spring-boot-starter</artifactId>
   <!--在引用时请在maven中央仓库搜索最新版本号-->
   <version>2.0.2</version>
</dependency>


knife4j配置：

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
    /**
     * 是否开启swagger，正式环境一般是需要关闭
     */
    @Value("${swagger.enabled}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).enable(enableSwagger).pathMapping("/").select()
            .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.*.controller"))
            .paths(PathSelectors.any()).build().apiInfo(apiInfo()).groupName("XXX服务-开放平台接口");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            // 设置文档标题(API名称)
            .title("XXX中心服务接口")
            // 文档描述
            .description("XXX服务接口文档说明......")
            // 服务条款URL
            .termsOfServiceUrl("http://XXX.XXX.XXX.XXX:8080/XXX")
            // 联系信息
            .contact(new Contact("em_aaron", "", ""))
            // 版本号
            .version("1.0.0").build();
    }
}


@Configuration
public class WebConfig implements WebMvcConfigurer {
    public static final String META_INF_RESOURCES = "classpath:/META-INF/resources/";
    ImmutableMap<String,
        String> webResourceMap = new ImmutableMap.Builder<String, String>().put("doc.html", META_INF_RESOURCES)
            .put("/webjars/**", "classpath:/META-INF/resources/webjars/").put("/service-worker.js", META_INF_RESOURCES)
            .put("/precache-manifest.*.js", META_INF_RESOURCES).build();

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        ImmutableSet<Map.Entry<String, String>> webResourceSet = webResourceMap.entrySet();
        webResourceSet.forEach(x -> registry.addResourceHandler(x.getKey()).addResourceLocations(x.getValue()));
    }
}

@Api(tags = "xxx接口API")
@ApiSort(2)
@RestController
@RequestMapping("/xxx")
public class xxxController {
    @ApiOperation(value = "验证接口", notes = "验证处理")
    @ApiOperationSupport(order = 1)
    @ResponseBody
    @RequestMapping(value = "/verify", method = {RequestMethod.POST}, consumes = 
        MediaType.APPLICATION_JSON_VALUE,
        produces = {"application/json; charset=UTF-8"})
    @SuppressWarnings(value = {"rawtypes"})
    public BaseResponse verify(@Validated @RequestBody Rq rq) {
        ....
        return BaseResponse.success();
    }
    .....

}

application.properties配置


#knife4j配置
knife4j.basic.enable=true
knife4j.basic.username=admin
knife4j.basic.password=123456
knife4j.markdowns=classpath:markdown/*

MD编写

Swagger在线文档之knife4j实战讲解