Knife4j practical explanation of Swagger online documentation

1. Background

       At present, the official UI page aesthetics and operation comfort of Swagger online documentation are difficult to satisfy relevant personnel such as development and testing; after investigation, it is found that knife4j is a very beautiful document plug-in, and the maturity of the plug-in community is relatively high. The blogger is here Share with your friends.

2. Introduction to knife4j

       knife4j is an online documentation solution that enhances Swagger UI and other functions that users need by secondary development based on Swagger; it supports custom documentation [.md], as well as new features such as grouping and sorting interface functions [due to new There are many features, so I won't list them all here] ;

Three, knife4j uses [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 write

Four, knife4j use effect

 

　　The last message, the above is the entire content of the blogger's article. If you think the blogger's article is not bad, please like it; if you are interested in the blogger's other server big data technology or the blogger himself, please pay attention to the blogger's blog , and welcome to communicate with bloggers at any time.

 

{{o.name}}

{{m.name}}