swagger

╰半夏微凉° 2024-04-18 04:17 65阅读 0赞

## swagger ##

**1. Swagger是什么？**

官方说法：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。swagger的一个最大的优点是能实时同步api与文档。

**2. spring boot 集成 Swagger**：目前项目是基于springboot框架开发的  
**3，Swagger使用步骤：**

*3.1 导入相关的maven依赖*

<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>

> 第一个是API获取的包，第二是官方给出的一个ui界面。

*3.2 创建相关实体，controller，响应对象，主要看其中的注解的使用。*

1 ，@Api(description = “用户相关接口文档”)每个controller上的注解，表示这个controller主要的业务模块。

> tags=“说明该类的作用，可以在UI界面上看到的注解”  
> value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

2，@ApiOperation(value = “用户首页”, notes = “访问页面”)每个方法的注解，表示这个方法的业务功能是什么。

> value=“说明方法的用途、作用”  
> notes=“方法的备注说明”

3， @ApiImplicitParams(value = \{@ApiImplicitParam(),@ApiImplicitParam()\})，用在请求的方法上，表示一组参数说明

4， @ApiParam(name = “userName”,value = “用户昵称”,required = true)方法参数注解，用在@ApiImplicitParams注解中，@ApiModelProperty(value = “用户id”, required = true)来说明引用类型每个属性的作用。

> name：参数名  
> value：参数的汉字说明、解释  
> required：参数是否必须传  
> paramType：参数放在哪个地方  
> · header --> 请求参数的获取：@RequestHeader  
> · query --> 请求参数的获取：@RequestParam  
> · path（用于restful接口）–> 请求参数的获取：@PathVariable  
> · body（不常用）  
> · form（不常用）  
> dataType：参数类型，默认String，其它值dataType=“Integer”  
> defaultValue：参数的默认值

5，@RequestHeader(“token”) String token 这个注解可以获取和设置header的参数，如用户身份签名。

6，@ApiIgnore()用于类，方法，方法参数。表示这个方法或者类被忽略。

**4. SpringBoot中Swagger2多包扫描问题**  
https://blog.csdn.net/teavamc/article/details/86654456