Spring Boot之Swagger 3.0

拼搏现实的明天。 2023-10-01 09:28 9阅读 0赞

**目录**

前言

什么是Swagger

有用的链接

项目集成

1、添加依赖

2、启动类配置

3、启动项目

分组

第一步：添加Swagger3自定义配置类（可选）

第二步：属性文件配置

授权

如何添加授权信息？

如何携带公共的请求参数？

格式美化

第一步：添加bootstrap-ui支持

第二步：启动项目

注解说明

示例代码

注解

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

### 前言 ###

这是一个突破性的变更

有关此项目的更多信息，请访问[API Documentation & Design Tools for Teams | Swagger][API Documentation _ Design Tools for Teams _ Swagger]

### **什么是Swagger** ###

Swagger 是最流行的 API 开发工具

**Swagger Codegen**: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

**Swagger UI**:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

**Swagger Editor**: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

**Swagger Inspector**: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

**Swagger Hub**：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

PS：

**Springfox Swagger**: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

### 有用的链接 ###

*  [参考文档][Link 1]
 *  [示例存储库][Link 2]
 *  [贡献指南][Link 3]
 *  [核心贡献者][Link 4]
 *  [开发和贡献指南][Link 5]
 *  [更改日志][Link 6]
 *  [开发环境][Link 7]
 *  [发布说明][Link 8]

### 项目集成 ###

本文将通过几个简单步骤教大家如何集成Swagger3

共三个步骤，步骤如下：

#### **1、添加依赖** ####

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

#### 2、启动类配置 ####

@EnableOpenApi
    @SpringBootApplication
    public class SwaggerApplication {
        public static void main(String[] args) {
            SpringApplication.run(SwaggerApplication.class, args);
        }
    }

`@EnableOpenApi`这个注解文档解释如下：

Indicates that Swagger support should be enabled.
    This should be applied to a Spring java config and should have an accompanying '@Configuration' annotation.
    Loads all required beans defined in @see SpringSwaggerConfig

**只有在配置类标注了`@EnableOpenApi`这个注解才会生成Swagger文档**

####  **3、添加配置类启动项目** ####

import io.swagger.annotations.ApiOperation;
    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.oas.annotations.EnableOpenApi;
    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;
    
    
    @EnableOpenApi
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
    
        @Bean public Docket createRestApi() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo()).select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any()).build();
        }
    
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("swagger-bootstrap-ui 示例 APIs")
                    .description("swagger-bootstrap-ui")
                    .termsOfServiceUrl("http://localhost:8080/")
                    .contact(new Contact("拾一", "http://localhost:8080/swagger-ui/index.html", "314569024@qq.com"))
                    .version("1.0")
                    .build();
        }
    
    
    }

#### 访问：[http://localhost:8080/swagger-ui/index.html][http_localhost_8080_swagger-ui_index.html] ####

![format_png][]

一个简单的Swagger后台接口文档，至此就搭建完成了。

可以看到，上面那个界面中，默认显示了一个`basic-error-controller`接口分组，但是我们并没有写；

通过在项目中查找我们发现，SpringBoot内部确实有这样一个控制器类，如下所示

![format_png 1][]

**说明Swagger默认的配置，会自动把@Controller控制器类添加到接口文档中**

###  在`Docket`中的方法`globalRequestParameters()`可以设置公共的请求参数，接收的参数是一个`List<RequestParameter>`，因此只需要构建一个`RequestParameter`集合即可，如下： ###

@Bean
    public Docket frontApi() {
       //构建一个公共请求参数platform，放在在header
       RequestParameter parameter = new RequestParameterBuilder()
          //参数名称
          .name("platform")
          //描述
          .description("请求的平台")
          //放在header中
          .in(ParameterType.HEADER)
          //是否必传
          .required(true)
          .build();
          //构建一个请求参数集合
          List<RequestParameter> parameters = Collections.singletonList(parameter);
            return new Docket(DocumentationType.OAS_30)
                    .....
                    .build()
                    .globalRequestParameters(parameters);
        }

### 格式美化 ###

#### 第一步：添加bootstrap-ui支持 ####

<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

#### 第二步：启动项目 ####

访问：boottapUI界面： [http://127.0.0.1:8080/doc.html][http_127.0.0.1_8080_doc.html]

原生界面：http://localhost:8080/swagger-ui/index.html

### 注解说明 ###

@Api：用在请求的类上，表示对类的说明
        tags="说明该类的作用，可以在UI界面上看到的注解"
        value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
    
    @ApiOperation：用在请求的方法上，说明方法的用途、作用
        value="说明方法的用途、作用"
        notes="方法的备注说明"
    
    @ApiImplicitParams：用在请求的方法上，表示一组参数说明
        @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
            name：参数名
            value：参数的汉字说明、解释
            required：参数是否必须传
            paramType：参数放在哪个地方
                · header --> 请求参数的获取：@RequestHeader
                · query --> 请求参数的获取：@RequestParam
                · path（用于restful接口）--> 请求参数的获取：@PathVariable
                · div（不常用）
                · form（不常用）    
            dataType：参数类型，默认String，其它值dataType="Integer"       
            defaultValue：参数的默认值
    
    @ApiResponses：用在请求的方法上，表示一组响应
        @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
            code：数字，例如400
            message：信息，例如"请求参数没填好"
            response：抛出异常的类
    
    @ApiModel：用于响应类上，表示一个返回响应数据的信息
                （这种一般用在post创建的时候，使用@RequestBody这样的场景，
                请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    
    @ApiModelProperty：用在POJO属性上，描述响应类的属性说明
    
    
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：状态码数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类
    
    @ApiIgnore：使用该注解忽略这个某个API或者参数；

#### 示例代码 ####

#####Controller代码
    @Override
        @ApiOperation(value = "post请求调用示例", notes = "invokePost说明", httpMethod = "POST")
        public FFResponseModel<DemoOutputDto> invokePost(@ApiParam(name="传入对象",value="传入json格式",required=true) @RequestBody @Valid DemoDto input) {
            log.info("/testPost is called. input=" + input.toString());
            return new FFResponseModel(Errcode.SUCCESS_CODE, Errcode.SUCCESS_MSG);
        }
    
    
    #####接口请求入参对象   
    @Data
    @ApiModel(value="演示类",description="请求参数类" )
    public class DemoDto implements Serializable {
    
        private static final long serialVersionUID = 1L;
    
        @NotNull
        @ApiModelProperty(value = "defaultStr",example="mockStrValue")
        private String strDemo;
    
        @NotNull
        @ApiModelProperty(example="1234343523",required = true)
        private Long longNum;
    
        @NotNull
        @ApiModelProperty(example="111111.111")
        private Double doubleNum;
    
        @NotNull
        @ApiModelProperty(example="2018-12-04T13:46:56.711Z")
        private Date date;
        
    }
    
    #####接口请求出参公共类
    @ApiModel(value="基础返回类",description="基础返回类")
    public class FFResponseModel<T> implements Serializable {
    
        private static final long serialVersionUID = -2215304260629038881L;
        // 状态码
        @ApiModelProperty(example="成功")
        private String code;
        // 业务提示语
        @ApiModelProperty(example="000000")
        private String msg;
        // 数据对象
        private T data;
    
    ...
    }
    
    #####接口请求出参实际数据对象
    @Data
    public class DemoOutputDto {
    
        private String res;
    
        @NotNull
        @ApiModelProperty(value = "defaultOutputStr",example="mockOutputStrValue")
        private String outputStrDemo;
    
        @NotNull
        @ApiModelProperty(example="6666666",required = true)
        private Long outputLongNum;
    
        @NotNull
        @ApiModelProperty(example="88888.888")
        private Double outputDoubleNum;
    
        @NotNull
        @ApiModelProperty(example="2018-12-12T11:11:11.111Z")
        private Date outputDate;
        
    }

[API Documentation _ Design Tools for Teams _ Swagger]: https://swagger.io/
[Link 1]: http://springfox.io/
[Link 2]: https://github.com/springfox/springfox-demos
[Link 3]: https://github.com/springfox/springfox/wiki/Contribution-guidelines
[Link 4]: http://springfox.github.io/springfox/contributors.html
[Link 5]: https://github.com/martypitt/swagger-springmvc/wiki/Development
[Link 6]: https://github.com/springfox/springfox/blob/master/docs/release-notes.md
[Link 7]: http://springfox.github.io/springfox/docs/current/#development-environment
[Link 8]: http://springfox.github.io/springfox/docs/current/#releasing
[http_localhost_8080_swagger-ui_index.html]: https://link.juejin.cn/?target=http%3A%2F%2Flocalhost%3A8080%2Fswagger-ui%2Findex.html
[format_png]: https://img-blog.csdnimg.cn/img_convert/239b749ec0d93357cb6fa6ad83317728.webp?x-oss-process=image/format,png
[format_png 1]: https://img-blog.csdnimg.cn/img_convert/f5166b050996afb06056e7e08c171dc1.webp?x-oss-process=image/format,png
[http_127.0.0.1_8080_doc.html]: http://127.0.0.1:8084/doc.html