SpingBoot集成Swagger和Knife4j

1.项目开发中编写接口文档实在是痛苦，于是打算引入swagger，之后发现swagger不够舒服，便又引入knife4j，springboot的相关依赖不再贴，下面是swagger和knife4j的相关依赖，版本有需求的可以上maven中央库获取

	    <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
                <!--整合Knife4j-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>

2.之后是swagger的config配置

package com.zqgame.cloudgame.configuration;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.context.annotation.Profile;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;

import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author zea
 * @date 2021年1月13日
 */
@Configuration
@EnableSwagger2
@Profile(value = {"dev"})
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
@ConditionalOnProperty(value = {"knife4j.enable"}, matchIfMissing = true)
public class SwaggerConfiguration {

	  /**
	     * 运营管理分组
	     *
	     * @return
	     */
	    @Bean(value = "indexApi")
	    public Docket indexApi() {
	        return new Docket(DocumentationType.SWAGGER_2)
	                .groupName("运营管理")
	                .apiInfo(apiInfo())
	                .select()
	                .apis(RequestHandlerSelectors.basePackage("com.zqgame.cloudgame.modules.dpss.rest"))
	                .paths(PathSelectors.any())
	                .build();
	    }

	    /**
	     * 后台管理分组
	     *
	     * @return
	     */
	    @Bean(value = "adminApi")
	    public Docket adminApi() {
	        return new Docket(DocumentationType.SWAGGER_2)
	                .groupName("后台管理")
	                .apiInfo(apiInfo())
	                .select()
	                .apis(RequestHandlerSelectors.basePackage("com.zqgame.cloudgame.modules.sys.rest"))
	                .paths(PathSelectors.any())
	                .build();
	    }
	    private ApiInfo apiInfo() {
	        return new ApiInfoBuilder()
	                .title("xxx服务接口定义和规范")
	                .description("xxx服务接口定义和规范")
	                .termsOfServiceUrl("http://localhost:8088/")
	                .contact(new Contact("zea", "zea_liu@163.com", "zea_liu@163.com"))
	                .version("1.0")
	                .build();
	    }


}

3.一些注解说明

@Profile(value = {"dev"}) 只在dev环境生效，可以用逗号隔开添加上测试环境，当然如果你想在生产环境也开发我也没有意见

@Api(tags = "[系统]登录验证")  写在类上，这个类的说明

@ApiOperation("用户登录") 写在方法上，对方法的说明

@ApiParam("平台Id") 写在controller层的方法的形参上，主要是对于@PathVariable 和@RequestParam 的一些注解

 @ApiModelProperty(value = "用户名",name = "name") 写在请求封装成实体类的实体的属性上name对应属性名称，value对应属性说明

@ApiIgnore 写在类上，一些类，比如后门类啥的不想开放出去，你懂的

4.swagger和knife4j的比较

个人看来knife4j看起来的确是比swagger要舒服和好用点，当然仁者见仁，看你自己选择吧

swagger 的访问地址是http://localhost:{port}/{context-path}/swagger-ui.html

knife4j的访问地址是http://localhost:{port}/{context-path}/doc.html

5.补充说明

有的小伙伴反馈说加载不出来或者报错，可能是因为拦截器进行了拦截，需要放开拦截

  Map<String, String> filterMap = new LinkedHashMap<>();
        filterMap.put("/webjars/**", "anon");
        filterMap.put("/swagger/**", "anon");
        filterMap.put("/v2/api-docs", "anon");
        filterMap.put("/swagger-ui.html", "anon");
        filterMap.put("/doc.html", "anon");
        filterMap.put("/swagger-resources/**", "anon");
       

只需要看他的key值就可以了，把key值放开拦截就可以开心的看到接口文档了

还有一点需要补充的是，如果你的接口没有指定请求类型，如post，get等 用的RequestMapping的话他会给post，get，put，delete各生成一个，所以最好是指定请求类型

感谢阅读，给个小爱心吧^_^