第二章：Swagger2

古城微笑少年丶 2024-03-30 14:05 118阅读 0赞

**目录**

背景介绍

什么是Swagger2

常用注解

SpringBoot整合Swagger2

生产环境下屏蔽Swagger2

修改Swagger2配置类

修改application.yml

使用maven package打包测试

运行测试

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

## 背景介绍 ##

> 在团队开发中，一个好的 API 文档不但可以减少大量的沟通成本，还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节，并在程序员之间代代相传。这种做法存在以下几个问题：
> 
> 1）API 接口众多，细节复杂，需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等，想要高质量的完成这份文档需要耗费大量的精力；
> 
> 2）难以维护。随着需求的变更和项目的优化、推进，接口的细节在不断地演变，接口描述文档也需要同步修订，可是文档和代码处于两个不同的媒介，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况；

> **Swagger2** 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：
> 
>  *  接口文档在线自动生成，文档随接口变动实时更新，节省维护成本；
>  *  支持在线接口测试，不依赖第三方工具；

## 什么是Swagger2 ##

> **Swagger2** 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用spring boot 整合它。作用：
> 
>  *  接口的文档在线自动生成；
>  *  功能测试；

## 常用注解 ##

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api</td> 
   <td>将类标记为 Swagger 资源。</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParam</td> 
   <td>表示 API 操作中的单个参数。</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParams</td> 
   <td>允许多个 ApiImplicitParam 对象列表的包装器。</td> 
  </tr> 
  <tr> 
   <td>@ApiModel</td> 
   <td>提供有关 Swagger 模型的其他信息。</td> 
  </tr> 
  <tr> 
   <td>@ApiModelProperty</td> 
   <td>添加和操作模型属性的数据。</td> 
  </tr> 
  <tr> 
   <td>@ApiOperation</td> 
   <td>描述针对特定路径的操作或通常是 HTTP 方法。</td> 
  </tr> 
  <tr> 
   <td>@ApiParam</td> 
   <td>为操作参数添加额外的元数据。</td> 
  </tr> 
  <tr> 
   <td>@ApiResponse</td> 
   <td>描述操作的可能响应。</td> 
  </tr> 
  <tr> 
   <td>@ApiResponses</td> 
   <td>允许多个 ApiResponse 对象列表的包装器。</td> 
  </tr> 
  <tr> 
   <td>@Authorization</td> 
   <td>声明要在资源或操作上使用的授权方案。</td> 
  </tr> 
  <tr> 
   <td>@AuthorizationScope</td> 
   <td>描述 OAuth2 授权范围。</td> 
  </tr> 
 </tbody> 
</table>

## SpringBoot整合Swagger2 ##

### 导入依赖 ###

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
        <exclusions>
            <exclusion>
                <artifactId>swagger-models</artifactId>
                <groupId>io.swagger</groupId>
            </exclusion>
        </exclusions>
    </dependency>
    
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.8.5</version>
    </dependency>
    
    
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.22</version>
    </dependency>

### 创建Swagger配置类 ###

@Configuration
    //开启Swagger2
    @EnableSwagger2
    //配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
    @Profile({"dev","test"})
    public class Swagger2Configuration extends WebMvcConfigurationSupport {
        //api接口包扫描路径
        public static final String
                SWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";
        //指定当前Swagger API文档版本
        public static final String VERSION = "1.0.0";
    
        /**
         * 创建API应用
         * apiInfo() 增加API相关信息
         * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
         * 本例采用指定扫描的包路径来定义指定要建立API的目录。
         * @return
         */
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    // 接口文档的基本信息
                    .apiInfo(apiInfo())
                    .select()
                    // 方法需要有ApiOperation注解才能生存接口文档
                    //.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    // 路径使用any风格
                    .paths(PathSelectors.any())
                    .build();
        }
    
        /**
         * 创建该API的基本信息（这些基本信息会展现在文档页面中）
         * 访问地址：http://项目实际地址/doc.html
         * @return
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("SpringBoot中使用Swagger2构建RestFul APIs")
                    .description("测试系统")
                    //.termsOfServiceUrl("http://www.**.com")
                    .version(VERSION)
                    .build();
        }
    
        @Override
        protected void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

> 1) 完成以上配置之后，通过mybatis-generator生成model和mapper； 2) 创建IBookService及BookServiceImpl实现类； 3) 创建BookController

### 综合案例 ###

![7d2654075e77400d97392d059ac28a3c.png][]

#### @Api ####

> **@Api**注解用在类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。

**案例演示**

@RestController
    @Api(value = "书本管理",tags = {"书本管理"}) //tags可以代替value属性
    @RequestMapping("/book")
    public class BookController {
        ...
    }

#### @ApiOperation ####

> **@ApiOperation**注解用在方法上，说明方法的作用，每一个url资源的定义。

<table> 
 <thead> 
  <tr> 
   <th><strong>属性</strong></th> 
   <th><strong>说明</strong></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>url的路径值</td> 
  </tr> 
  <tr> 
   <td>tags</td> 
   <td>如果设置这个值、value的值会被覆盖</td> 
  </tr> 
  <tr> 
   <td>produces</td> 
   <td>返回的格式类型例如："application/json, application/xml"</td> 
  </tr> 
  <tr> 
   <td>consumes</td> 
   <td>接收请求参数的类型例如："application/json, application/xml"</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>是否在文档中显示</td> 
  </tr> 
  <tr> 
   <td>notes</td> 
   <td>注释说明</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>返回的对象</td> 
  </tr> 
  <tr> 
   <td>responseContainer</td> 
   <td>这些对象是有效的 "List", "Set" or "Map".，其他无效</td> 
  </tr> 
  <tr> 
   <td>responseReference</td> 
   <td>指定对响应类型的引用。指定的引用可以是本地的，也可以是远程的*将按原样使用，并覆盖任何指定的response()类</td> 
  </tr> 
  <tr> 
   <td>responseHeaders</td> 
   <td>响应旁边提供的可能标题列表</td> 
  </tr> 
  <tr> 
   <td>httpMethod</td> 
   <td>"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"</td> 
  </tr> 
  <tr> 
   <td>code</td> 
   <td>http的状态码 默认 200</td> 
  </tr> 
 </tbody> 
</table>

**案例演示**

@ApiOperation(value = "查询所有书本信息", notes = "查询返回所有书本信息集合",
                produces = "application/json")
    @GetMapping(value="/queryAll")
    public JsonResponseBody<List<Book>> queryAll(){
        try {
            return bookService.queryAll();
        } catch (Exception e) {
            e.printStackTrace();
            return new JsonResponseBody<>(500,e.getMessage());
        }
    }

#### @ApiImplicitParam ####

> **@ApilmplicitParam** 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入；

<table> 
 <thead> 
  <tr> 
   <th><strong>属性</strong></th> 
   <th><strong>说明</strong></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>paramType</td> 
   <td>参数放在哪个地方</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>参数名称</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>参数代表的含义</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td>参数类型</td> 
  </tr> 
  <tr> 
   <td>dataTypeClass</td> 
   <td>参数类型</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>是否必要</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td>参数的默认值</td> 
  </tr> 
 </tbody> 
</table>

**paramType**

<table> 
 <thead> 
  <tr> 
   <th>类型</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>path</td> 
   <td>以地址的形式提交数据，用于restful接口。请求参数采用@PathVariable获取</td> 
  </tr> 
  <tr> 
   <td>query</td> 
   <td>直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取</td> 
  </tr> 
  <tr> 
   <td>body</td> 
   <td>以流的形式提交，仅支持POST。请求参数采用@RequestBody获取</td> 
  </tr> 
  <tr> 
   <td>header</td> 
   <td>参数在request headers里边提交。请求参数采用@RequestHeader获取</td> 
  </tr> 
  <tr> 
   <td>form</td> 
   <td>以form表单的形式提交，仅支持POST。</td> 
  </tr> 
 </tbody> 
</table>

**案例演示**

@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息")
    @ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )
    @GetMapping("/querySingleBook")
    public Book querySingleBook(String bookid){
        JsonResponseBody<Book> json = bookService.selectByPrimaryKey(bookid);
        return json.getData();
    }

#### @ApiImplicitParams ####

> **@ApilmplicitParams** 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述， 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中；

**案例演示**

@ApiOperation(value = "新增书本信息", notes = "新增书本信息"
                ,produces = "application/json",consumes = "application/json")
    @ApiImplicitParams({
                @ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),
                @ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),
                @ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
    })
    @PostMapping("/addBook")
    public JsonResponseBody<?> addBook(@RequestParam String bookname,
                                       @RequestParam Double price,
                                       @RequestParam String booktype){
        return bookService.insert(Book.builder()
            .bookid(UUID.randomUUID().toString().replace("-",""))
            .bookname(bookname)
            .booktype(booktype)
            .price(price)
            .build());
    }

#### @ApiModel和@ApiModelProperty ####

> **@ApiModel**注解描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候；
> 
> **@ApiModelProperty**注解描述一个model的属性。

<table> 
 <thead> 
  <tr> 
   <th><strong>属性</strong></th> 
   <th><strong>说明</strong></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>字段说明</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>参数名称</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td>参数类型</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>在文档中隐藏</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>是否必要</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td>举例说明</td> 
  </tr> 
  <tr> 
   <td>notes</td> 
   <td>注释说明</td> 
  </tr> 
 </tbody> 
</table>

**案例演示**

Controller

@ApiOperation(value="修改书本信息",notes = "修改书本信息")
    @PostMapping("/editBook")
    public JsonResponseBody<?> editBook(@RequestBody Book book){
        return bookService.updateByPrimaryKey(book);
    }

> 注意：在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息，因为在这里的输入参数是实体对象，而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。

Book实体类

@Data
    @Builder
    @AllArgsConstructor
    @NoArgsConstructor
    @ApiModel(value="书本对象")
    public class Book implements Serializable {
    
        /**
         * 书本编号
         */
        @ApiModelProperty(value="书本编号")
        private String bookid;
    
        /**
         * 书本名称
         */
        @ApiModelProperty(value="书本名称")
        private String bookname;
    
        /**
         * 书本价格
         */
        @ApiModelProperty(value="书本价格")
        private Double price;
    
        /**
         * 书本类型
         */
        @ApiModelProperty(value="书本类型")
        private String booktype;
    
        private static final long serialVersionUID = 1L;
    }

#### @ApiParam ####

> 作用在方法的参数上，用来描述接口的参数信息(一个参设置一个)
> 
> `@ApiParam`必须与`@RequestParam`、`@PathVariable`和`@RequestHeader`一起使用。

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>参数名称</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>参数简单描述</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td>描述参数默认值</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>是否为必传参数, false:非必传; true:必传</td> 
  </tr> 
  <tr> 
   <td>allowMultiple</td> 
   <td>指定参数是否可以通过多次出现来接收多个值</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>隐藏参数列表中的参数</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td>非请求体(body)类型的单个参数示例</td> 
  </tr> 
  <tr> 
   <td>examples</td> 
   <td>@Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例，仅适用于请求体类型的请求</td> 
  </tr> 
 </tbody> 
</table>

**案例演示**

@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
    @PostMapping("/addBooks")
    public JsonResponseBody<?> addBooks(
                @ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
                @ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
                @ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
          System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
        return new JsonResponseBody<>();
    }

## 生产环境下屏蔽Swagger2 ##

> 为了保证接口文档的安全，禁用了生产环境的加载，具体说明请看：
> 
> 参考地址：[https://www.jianshu.com/p/fa3230ffb27c][https_www.jianshu.com_p_fa3230ffb27c]
> 
> **一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!**
> 
> **一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!**
> 
> **一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!**

### 修改Swagger2配置类 ###

> 添加@Profile注解，指明在何种环境下可以使用Swagger2，一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2；而在生产(dev)环境下不能使用Swagger2。

@Configuration
    //开启Swagger2
    @EnableSwagger2
    //配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
    @Profile({"dev","test"})
    public class Swagger2Configuration extends WebMvcConfigurationSupport {
        
        ...
    
        @Override
        protected void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("doc.html")
    .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

### 修改application.yml ###

> 修改application.yml文件，配置项目系统的运行环境（dev/test/prod）

spring:
      #配置swagger2生产和测试环境不可用
      profiles:
        active: prod

### 使用maven package打包测试 ###

![824ace2624374ccb817a41c5757bef9a.png][]

> ### 运行测试 ###
> 
> 打开CMD，跳转到target目录，输入命令：java -jar .\\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境，具体请参考以下配置：

> 开发环境：dev；
> 
> 生产环境：prod；
> 
> 测试环境：test；

![bd0f1efd981f43329415a48f6ac766fc.png][]

##  **以上就是今天有关于Swagger2的介绍和使用！** ##

[7d2654075e77400d97392d059ac28a3c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/30/644131e8757f4aec9345017088860767.png
[https_www.jianshu.com_p_fa3230ffb27c]: https://www.jianshu.com/p/fa3230ffb27c
[824ace2624374ccb817a41c5757bef9a.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/30/eec5f210d4fb48258a64b8b3fdf72295.png
[bd0f1efd981f43329415a48f6ac766fc.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/30/8209b62a68684bffbd9b0f779beae287.png