SpringBoot与Swagger的集成

swagger 介绍

swagger是一个完整的框架，用于自动生成接口文档，可极大减少后台开发人员的接口文档编辑所消耗的时间，并保证接口文档风格的一致性。

swagger 的使用

1. 使用maven导入Swagger

在项目的pom.xml文件中插入如下代码，版本号自行选择。

<!-- Swagger -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<versuion>2.6.1</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<versuion>2.6.1</version>
</dependency>

2. 创建Swagger的配置类SwaggerConf

package com.test.swagger.conf;

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.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;

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConf {

    @Bean
    public Docket createDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
                .select()
                //控制暴露出去的路径下的实例
                //如果某个接口不想暴露,可以使用以下注解
                //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下
                .apis(RequestHandlerSelectors.basePackage("com.test")) //定义swagger扫描的包
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        Contact contact = new Contact("开发者","",""); //参数说明：name：作者姓名，url：作者的个人主页，email：作者的联系邮箱
        return new ApiInfoBuilder()
                .title("swagger建议搭建测试项目") //页面标题
                .contact(contact) //创建人
                .version("0.0.1") //版本号，建议与项目的版本对应一致
                .description("API 描述，测试swagger集成效果") //API描述
                .build();
    }
}

3. 创建一个测试controller，并配置其接口文档的描述，使用swagger的相应注解即可

package com.test.swagger.controller;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Description;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping(value = "/test")
public class TestController {

    @RequestMapping(method = RequestMethod.GET, value = "/testSwagger")
    @ApiOperation(value = "测试swagger自动生成接口文档")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "param1", dataType = "int", required = true, paramType = "query", value = "需要被校验的值，正确值为5"),
            @ApiImplicitParam(name = "param2", dataType = "String", required = true, paramType = "query", value = "被拼接的参数")
    })
    public String test(int param1, String param2){
        if (param1 == 5){
            return "这个就是返回的结果，两个参数进行拼接："+param2+param1;
        }
        return "参数校验异常";
    }

}

4. 项目基于SpringBoot集成的swagger

测试项目搭建好，并且按照上述配置了swagger后，便可启动项目测试一下结果。

一个简单的接口文档搭建完毕了，后期将会更新swagger的一些注解详情。