springboot集成swagger

一、概要

　　Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

二、详细步骤

　　1.添加maven依赖

 <!--引入swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.20</version>
            <exclusions>
                <exclusion>
                    <groupId>com.fasterxml.jackson.core</groupId>
                    <artifactId>jackson-annotations</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

　　2.在pom中添加插件

　　　　　　<plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>2.14.1</version>
                <configuration>
                    <systemPropertyVariables>
                        <io.springfox.staticdocs.outputDir>${project.build.directory}/swagger/api/1.3.0</io.springfox.staticdocs.outputDir>
                        <io.swagger.json.uris>/v2/api-docs?group=api</io.swagger.json.uris>
                        <io.swagger.json.output.name>swagger-pai-v1.json</io.swagger.json.output.name>
                    </systemPropertyVariables>
                    <argLine>-Xmx256M -XX:MaxPermSize=128M</argLine>
                    <parallel>false</parallel>
                    <testFailureIgnore>true</testFailureIgnore>
                    <includes>
                        <include>**/*.java</include>
                    </includes>
                </configuration>
            </plugin>

三、添加配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(setHeaderToken())　//如果使用到了token，这里加入token设置
                .apiInfo(apiInfo())
                .groupName("api")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.web.api")) //api接口目录
                .paths(PathSelectors.any())
                .build();
    }

    private List<Parameter> setHeaderToken() {
        ParameterBuilder tokenPra = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPra.name("Token").description("接口校验令牌").modelRef(new ModelRef("string")).defaultValue(TokenUtils.get()).parameterType("header")
                .required(true).build();
        pars.add(tokenPra.build());

        return pars;
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("小明", "", "xiaoming@qq.com");

        return new ApiInfoBuilder().version("1.3").title("swagger测试接口").description("swagger测试接口").contact(contact).license("") .licenseUrl("http://www.qq.com").build(); } 
}

SwaggerConfig 类可随意放在代码的目录中，加入这些配置后，启动springboot项目，访问 http://localhost:8080/swaggerDemo/swagger-ui.html  ，其中swaggerDemo是项目的上下文，如果配置了不用上下文，也可以直接

http://localhost:8080/swagger-ui.html 进行启动，swagger的json路径为：http://localhost:8080/swaggerDemo/v2/api-docs?group=api，可以看到完整路径

四、生成swagger.json文件
编写测试类，在mvn install的时候可以将swagger.json生成到你在plugin配置的路径中

@WebAppConfiguration
//// 让 JUnit 运行 Spring 的测试环境， 获得 Spring 环境的上下文的支持
@RunWith(SpringRunner.class)
//// 获取启动类，加载配置，确定装载 Spring 程序的装载方法，它回去寻找 主配置启动类（被 @SpringBootApplication 注解的）
@SpringBootTest
public class SwaggerTest {

    @Autowired
    private WebApplicationContext wac;

    private MockMvc mockMvc;


    @Before
    public void setup(){
        //init applicationContext
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
    }

    @Test
    public void getSwaggerJson() throws Exception{
        //获取插件中配置的swagger文件输出地址
        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
        //获取插件中配置的swagger.json的访问地址,有几个接口分组就有几个访问地址，地址必须是swagger2controller中原生的，如果是在web.xml自定义的则无法访问，因为mock的服务不会解析web.xml
        String uris = System.getProperty("io.swagger.json.uris");
        //获取插件中配置的每个json文件的名称，名称可配置多个，有几个接口分组就有几个名称， 名称的格式必须是：组件标识-接口分组标识-接口版本号，例如：swagger-api-v1
        String swaggerOutName = System.getProperty("io.swagger.json.output.name");
        String[] uriArray = uris.trim().split(",");
        String[] swaggerOutNameArray = swaggerOutName.trim().split(",");

        for (int i = 0; i < uriArray.length; i++){
            MvcResult mvcResult = this.mockMvc
                    .perform((MockMvcRequestBuilders.get(uriArray[i])) // 测试的相对地址
                            .accept(MediaType.APPLICATION_JSON_UTF8)) // accept response content type
                    .andExpect(MockMvcResultMatchers.status().isOk())  // 期待返回状态吗码200
                    .andReturn();

            MockHttpServletResponse response = mvcResult.getResponse();
            String swaggerJson = response.getContentAsString();
            Files.createDirectories(Paths.get(outputDir));
            try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, swaggerOutNameArray[i]), StandardCharsets.UTF_8)){
                writer.write(swaggerJson);
            }
        }

    }
}

这样生成的json文件就会在项目的target目录的/swagger/api/1.3.0下，名字叫 swagger-pai-v1.json，路径及文件名都是在plugin中配置的