SpringBoot集成SwaggerUI

SwaggerUI作用：
1.所有接口方法可以动态的生成API文档,开发无需手动编写文档
2.研发可以直接点击对应接口完成自测
3.测试人员可以测试。

1.pom.xml文件添加依赖

    <properties>
        <swagger.version>2.6.1</swagger.version>
    </properties>        
    <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
    </dependency>

    <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
    </dependency>

2.创建swagger配置文件

创建 com.course.config 包，包下面创建AwaggerConfig.java文件，内容如下：

package com.course.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select()
                .paths(PathSelectors.regex("/.*"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("我的借口文档")
                .contact(new Contact("gaoyx","","gaoyx@*****.com.cn"))
                .description("这是我的swagger生成的接口文档")
                .version("1.0.0.0")
                .build();

    }
}

访问 http://localhost:8888/swagger-ui.html 是只有文档，没有具体方法的。只是代表文档可以生成了。

3.在方法类中类中定义为bean

给上文【SpringBoot—返回cookies信息的get接口开发】中MyGetMethod.java的方法定义对应的标签。
public class MyGetMethod {}上方加：
@Api(value = "/",description = "这是我全部的get方法")
public String getCookies(HttpServletResponse response){}上方加
@ApiOperation(value = "通过这个方法获得Cookies",httpMethod = "GET")
public String getwithcookies(HttpServletRequest request) {}上方加
@ApiOperation(value = "要求客户端携带cookies访问",httpMethod ="GET")
public Map<String,Integer> getlist(@RequestParam Integer start,
@RequestParam Integer end){} 上方加
@ApiOperation(value = "需要携带cookies信息才能访问的get请求,第一种方法",httpMethod ="GET")
public Map<String,Integer> myGetlist(@PathVariable Integer start,
@PathVariable Integer end){}上面加
@ApiOperation(value = "需要携带cookies信息才能访问的get请求,第二种方法",httpMethod="GET")

4.修改扫描目录

原来的Application.java文件中 @ComponentScan标签对应的扫描目录是 ("com.course.server"),现在改为 ("com.course")，因为要把 Swagger 的配置目录 com.course.config包含进去。

5.访问及验证

再次运行Application.java，访问 http://localhost:8888/swagger-ui.html，可以看到接口文档中对应的方法：

swagger文档.png

点开/get/with/param 接口，填写参数 1，2 点击 Try it out！即可测试。

测试接口.png

接口返回.png

我感觉还是很好用的。
公司的spring项目是结合Gradle 使用的，也是可以集成 Swagger的，文章上面是在 pom.xml文件中加依赖，gradle项目是在 build.gradle中加依赖，其他不变。只是有一些方法和依赖包可能报不存在，不存在的地方先注释掉即可。也可以成功生成Swagger接口文档。可以推荐给研发同志使用。

并给也可以根据环境来设置是否启动 Swagger，比如生成环境就可以不暴露出来。
配置如下：

@Value("${swagger.enable}")
private boolean enableSwagger;

@Bean 
public Docket customImplementation(){
    return new Docket(SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(enableSwagger) //<--- Flag to enable or disable possibly loaded using a property file
        .includePatterns(".*pet.*");
}

如果只在在dev和test环境中启用，则配置

swagger:
  enable: true

<完！>