《SpringBoot集成Swagger接口文档》

简介

Swagger不仅可以快速形成API接口文档，而且还可以通过它进行接口测试，使用非常方便快捷。

• 1.快速抽取API接口文档
• 2.接口快捷测试

快速集成

• 1.通过maven方式引入依赖

        <!--Swagger2文档生成-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

• 2.增加Swagger的配置文件

通过配置文件可以配置Swagger的api包扫码位置，也可以配置Swagger文档的标题，作者，描述等基本文档信息。

import org.springframework.beans.factory.annotation.Value;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;


@Configuration
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api文档标题")
                .description("api文档描述")
                .termsOfServiceUrl("http://baidu.com")//（不可见）条款地址
                .version("1.0")
                .build();
    }
}

• 3.在Controller类中增加接口注解（提取API文档）

注解作用范围	API	使用位置
对象属性	@ApiModelProperty	用在出入参数对象的字段上
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

paramType可选类型:

path 以地址的形式提交数据
query 直接跟参数完成自动映射赋值
body 以流的形式提交 仅支持POST
header 参数在request headers 里边提交
form 以form表单的形式提交 仅支持POST

---

代码示例:

    @ApiOperation(value = "增加用户",notes = "增加用户")
    @ResponseBody
    @PostMapping("/add")
    public int addUser(@RequestBody User user){
        return userService.addUser(user);
    }

    @ApiOperation(value = "查询所有用户",notes = "查询所有用户信息",httpMethod = "GET",response = User.class,produces = "application/json")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum", value = "分页页数", required = false, dataType = "int",paramType = "query"),
            @ApiImplicitParam(name = "pageSize", value = "每分页数", required = false, dataType = "int",paramType = "query"),
    })
    @ResponseBody
    @GetMapping("/all")
    public List<User> findAllUser(
            @RequestParam(name = "pageNum", required = false, defaultValue = "1")
                    int pageNum,
            @RequestParam(name = "pageSize", required = false, defaultValue = "10")
                    int pageSize){
        //开始分页
        PageHelper.startPage(pageNum,pageSize);
        return userService.findAllUser(pageNum,pageSize);
    }

传递进出参数对象 User类配置API注解

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "用户信息")
public class User {

    @ApiModelProperty(value = "ID",required = true)
    int id;
    @ApiModelProperty(value = "用户ID",required = true)
    String uid;
    @ApiModelProperty(value = "用户名称",required = true)
    String username;
    @ApiModelProperty(value = "用户密码",required = true)
    String password;
    @ApiModelProperty(value = "用户手机号码",required = true)
    String phone;
    @ApiModelProperty(value = "用户Email",required = false)
    String email;

    //setter/getter.......
}

• 4.在应用程序Application启动类上添加注解
  这个@EnableSwagger2注解千万别忘了加在启动类上

@SpringBootApplication
@EnableSwagger2//开启Swagger2
public class BaseframeApplication
{
    public static void main(String[] args) {
        SpringApplication.run(BaseframeApplication.class, args);
    }
}

• 5.启动服务查看自动生成的API文档

访问 http://localhost:port/swagger-ui.html 可以看到刚刚配置的API文档

image.png

/user/add 接口中 ‘/user’ 是当前类上的路径。

我们不只可以查看API文档，还可以通过每个接口上的 Try it out!按钮 访问服务测试接口的有效性。