Swagger怎么使用

我不是女神ヾ 2023-10-04 20:57 29阅读 0赞

## 1、什么是Swagger？ ##

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。

（https://github.com/OAI/OpenAPI-Specification）

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，Swagger是一个在线接口文档的生成工具，前后端开发人员依据接口文档进行开发。 (https://swagger.io/)

只要添加Swagger的依赖和配置信息即可使用它。

## 2、idea配置swagger ##

**1、在pom配置**

<dependency>  
<groupId>com.spring4all</groupId>  
<artifactId>swagger-spring-boot-starter</artifactId>  
</dependency>

![70e0de6e01284a268a798fdadb4eaaaf.png][]

2、在 bootstrap.yml中配置

swagger:
      title: "xxxxx管理系统"
      description: "内容系统管理系统对课程相关信息进行业务管理数据"
      base-package: com.xuecheng.content
      enabled: true
      version: 1.0.0

说明：base-package为扫描的包路径，扫描Controller类。

Spring Boot 可以集成Swagger，Swaager根据Controller类中的注解生成接口文档 ，在模型类上也可以添加注解对模型类中的属性进行说明，方便对接口文档的阅读。

3、比如：下边标红的属性名称，可以通过swaager注解标注一个中文名称，方便阅读接口文档。

![1ba2258115e04ca690c3d5901039b8b1.png][]

4、标注的方法非常简单：  
找到模型类，在属性上添加注解：

![9924198d8f2149f7a16654c7b3982dcc.png][]

5、重启服务，再次进入接口文档，如下图：

![003d1c141c854e458a6b02f7278d9cbe.png][]

## 3、Swaager的常用注解如下： ##

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：  
@Api：修饰整个类，描述Controller的作用  
@ApiOperation：描述一个类的一个方法，或者说一个接口  
@ApiParam：单个参数描述  
@ApiModel：用对象来接收参数  
@ApiModelProperty：用对象接收参数时，描述对象的一个字段  
@ApiResponse：HTTP响应其中1个描述  
@ApiResponses：HTTP响应整体描述  
@ApiIgnore：使用该注解忽略这个API  
@ApiError ：发生错误返回的信息  
@ApiImplicitParam：一个请求参数  
@ApiImplicitParams：多个请求参数

@ApiImplicitParam属性：

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>取值</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>paramType</td> 
   <td></td> 
   <td>查询参数类型</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>path</td> 
   <td>以地址的形式提交数据</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>query</td> 
   <td>直接跟参数完成自动映射赋值</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>body</td> 
   <td>以流的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>header</td> 
   <td>参数在request headers 里边提交</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>form</td> 
   <td>以form表单的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td></td> 
   <td>参数的数据类型 只作为标志说明，并没有实际验证</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>Long</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>String</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td></td> 
   <td>接收参数名</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td></td> 
   <td>接收参数的意义描述</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td></td> 
   <td>参数是否必填</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>true</td> 
   <td>必填</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>false</td> 
   <td>非必填</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td></td> 
   <td>默认值</td> 
  </tr> 
 </tbody> 
</table>

## 4、面试 ##

1、SpringBoot接口开发的常用注解有哪些？

@Controller 标记此类是一个控制器，可以返回视图解析器指定的html页面，通过@ResponseBody可以将结果返回json、xml数据。  
@RestController 相当于@ResponseBody加 @Controller，实现rest接口开发，返回json数据，不能返回html页面。  
@RequestMapping 定义接口地址，可以标记在类上也可以标记在方法上，支持http的post、put、get等方法。  
@PostMapping 定义post接口，只能标记在方法上，用于添加记录，复杂条件的查询接口。  
@GetMapping 定义get接口，只能标记在方法上，用于查询接口的定义。  
@PutMapping 定义put接口，只能标记在方法上，用于修改接口的定义。  
@DeleteMapping 定义delete接口，只能标记在方法上，用于删除接口的定义。  
@RequestBody 定义在方法上，用于将json串转成java对象。  
@PathVarible 接收请求路径中占位符的值.  
@ApiOperation swagger注解，对接口方法进行说明。  
@Api wagger注解，对接口类进行说明。  
@Autowired 基于类型注入。  
@Resource 基于名称注入，如果基于名称注入失败转为基于类型注入。

[70e0de6e01284a268a798fdadb4eaaaf.png]: https://img-blog.csdnimg.cn/70e0de6e01284a268a798fdadb4eaaaf.png
[1ba2258115e04ca690c3d5901039b8b1.png]: https://img-blog.csdnimg.cn/1ba2258115e04ca690c3d5901039b8b1.png
[9924198d8f2149f7a16654c7b3982dcc.png]: https://img-blog.csdnimg.cn/9924198d8f2149f7a16654c7b3982dcc.png
[003d1c141c854e458a6b02f7278d9cbe.png]: https://img-blog.csdnimg.cn/003d1c141c854e458a6b02f7278d9cbe.png