SpringBoot 整合swagger2

SpringBoot 整合swagger2

环境：SpringBoot 2.0.+

1 普通版

1 pom文件依赖

        <!-- swagger2API文档支持 -->
        <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>

2 新增配置文件

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

/**
 * 访问 http://localhost:8080/swagger-ui.html
 * Profile(value = {"dev", "test"}) 指定spring.profiles.active=dev/test才加载,生产环境不加载
 */
@Configuration
@EnableSwagger2
@Profile(value = {"dev", "test"})
public class Swagger2Configuration {

    /**
     * 通过 createRestApi函数来构建一个DocketBean
     * 函数名,可以随意命名,喜欢什么命名就什么命名
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
                .apiInfo(apiInfo())
                .select()
                //控制暴露出去的路径下的实例
                //如果某个接口不想暴露,可以使用以下注解
                //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下RequestHandlerSelectors.basePackage("com.system.controller")
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();

    }
    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Soring Boot API title")
                .version("1.0")
                //描述
                .description("Soring Boot Project API 描述")
                .build();
    }

}

3 验证

1. controller

@RestController
@RequestMapping("/test")
@Api(description = "swagger2 API")
public class TestController {

    public static final Logger logger = LoggerFactory.getLogger(TestController.class);

    @ApiOperation(value = "描述1", notes = "描述2", response = BaseRequest.class)
    @RequestMapping(value = "/test", method = RequestMethod.GET)
    public String test(@ApiParam(name="name",value="name",required=false) String name) {
        logger.info("name:" + name);
        return "success";
    }
}

2. 页面浏览
   http://localhost:8080/swagger-ui.html
   

2 加强版

#配置swagger配置
knife4j:
  basic: 
    username: admin
    password: 123
    enable: true #开启认证
  production: false #默认是false ,屏蔽所有Swagger的相关资源
  enable: true #是否开启swagger

1. 直接上配置代码

引用包SpringBoot 自动引入

@Configuration
@EnableKnife4j
@EnableSwagger2
public class Knife4jConfig {
        @Value("${version:1.0}")
    private String version;

    @Bean
    public Docket api() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<>();
        tokenPar.name("token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build();
        parameters.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("V1")
                .apiInfo(apiInfo()).forCodeGeneration(true)
                .select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("/api/v1/.*"))
                .build()
                .globalOperationParameters(parameters);
    }

    @Bean
    public Docket apiV2() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        ParameterBuilder userId = new ParameterBuilder();
        ParameterBuilder userName = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<>();
        tokenPar.name("token")
                .modelRef(new ModelRef("string"))
                .parameterType("header").required(false)
                .build();
        userId.name("userId")
                .modelRef(new ModelRef("string"))
                .parameterType("header").required(false)
                .build();
        userName.name("userName")
                .modelRef(new ModelRef("string"))
                .parameterType("header").required(false)
                .build();
        parameters.add(tokenPar.build());
        parameters.add(userId.build());
        parameters.add(userName.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("V2")
                .apiInfo(apiInfo()).forCodeGeneration(true)
                .select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("/api/v2/.*"))
                .build()
                .globalOperationParameters(parameters);
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .version(version)
                .build();

    }
}

2. 结果