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

「爱情、让人受尽委屈。」 2021-11-29 19:58 400阅读 0赞

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

--------------------

### 1、导入jar依赖包 ###

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

<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\#/][http_127.0.0.1_8081_swagger-ui.html]   如果你是将服务部署在云服务器上（假设ip 为 47.47.47.47），访问的端口是8080，那么别人都可以通过[http://47.47.47.47:8080/swagger-ui.html\#/][http_127.0.0.1_8081_swagger-ui.html]  访问接口文档

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2NoZW56ejI1NjA_size_16_color_FFFFFF_t_70][]

在这个页面上我们除了可以看到接口的参数要求，还可以像在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

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

[http_127.0.0.1_8081_swagger-ui.html]: http://127.0.0.1:8081/swagger-ui.html#/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2NoZW56ejI1NjA_size_16_color_FFFFFF_t_70]: /images/20211129/b7f36e7bb80a40bc83da848345624fda.png