SpringBoot学习记录----利用Springfox和Swagger-ui生成API文档

记录一下公司用来生成初步API接口文档的swagger使用方法，以及自己配置时遇到的坑，下面直接进入正文。

---

1、导入jar依赖包

目前导入的是springfox-swagger2和springfox-swagger-ui的最新版。springfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来

      <!-- swagger dependency -->
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
      </dependency>

      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
      </dependency>

2、设置配置文件

这个配置类主要设置swagger页面上的部分信息。

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        //Docket是Swagger重要的构造器，为swagger配置提供默认值和方法
        //DocumentationType.SWAGGER_2表示使用swagger版本2.0
        return new Docket(DocumentationType.SWAGGER_2)
                //传入自定义的API描述信息
                .apiInfo(apiInfo())
                //返回一个api选择构建器
                .select()
                //指定扫描的包
                .apis(RequestHandlerSelectors.basePackage("czz.study.api"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 生成一个包含自定义信息的ApiInfo类
     * @return ApiInfo类
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger页面标题")
                .description("swagger页面描述")
                //指定服务声明地址（跟swagger访问地址无关）
                .termsOfServiceUrl("http://localhost:8081/")
                //添加联系人信息
                .contact(new Contact("联系人名称","URL","邮箱地址"))
                //版本描述
                .version("1.0")
                .build();
    }
}

@EnableSwagger2 注解表示启动Swagger支持，并加载所有默认需要的Beans。

3、描述接口

 

/**
 * Swagger测试Api
 *
 * @author czz
 * @version 1.0
 * @date 2019/7/27 21:18
 */
@Api(tags = "Swagger测试")
@RestController
@RequestMapping("/api/")
public class SwaggerApi {

    @ApiOperation(value = "求和功能", notes = "这是一个求和功能，计算a+b的值")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "a", value = "第一个值a", paramType = "query"),
            @ApiImplicitParam(name = "b", value = "第二个值b", paramType = "query")
    })
    @GetMapping("/find/get")
    public Integer getData(@RequestParam Integer a, @RequestParam Integer b) {
        return a + b;
    }

}

在我们的接口上添加Swagger的注解。除了SpringMVC提供的注解，我们还需要使用以下注解描述接口

• @Api()用于类名
• @ApiOperation()用于方法名
• @ApiParam()用于参数说明
• @ApiModel()用于实体类
• @ApiModelProperty用于实体类属性

 

4、访问API接口文档

启动项目，在浏览器中输入接口文档地址，地址的基本格式是 ip:端口/swagger-ui.html#/ 。例如，如果我要在本地访问，同时我服务端口是8081，那访问地址就是 http://127.0.0.1:8081/swagger-ui.html#/   如果你是将服务部署在云服务器上（假设ip 为 47.47.47.47），访问的端口是8080，那么别人都可以通过http://47.47.47.47:8080/swagger-ui.html#/  访问接口文档

 在这个页面上我们除了可以看到接口的参数要求，还可以像在postman上一样调用测试这个接口。如果担心安全性，怕被其他人调用，我们可以通过 Spring security 给访问的时候加上账号和密码。具体操作如下：

1、添加依赖

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-security</artifactId>
</dependency>

2、在SpringBoot配置文件application.yml中配置账号密码

security:
  basic:
    path: /swagger-ui.html,/v2/api-docs # 拦截的路径
  user:
    # 配置用户名
    name: czz
    #密码
    password: 123456

这样，我们在访问的时候就会要求我们输入账号密码了。