Swagger知识点整理

一、简介

Swagger是一款目前世界最流行的API管理工具，能够管理API的整个生命周期，从设计、文档到测试与部署。用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

1. 特点：

• 代码侵入式注解。
• 遵循YAML文档格式。
• 非常适合三端（PC、iOS及Android）的API管理，尤其适合前后端完全分离的架构模式。
• 减少没有必要的文档，符合敏捷开发理念。
• 功能强大。

2. 优点：

• 大大减少前后端的沟通
• 方便查找和测试接口
• 提高团队的开发效率
• 方便了解项目

3. 作用：

• 接口的文档在线自动生成
• 功能测试

4. 主要组成部分：

• Swagger-tools:提供各种与Swagger进行集成和交互的工具。
• Swagger-core: 用于Java/Scala的的Swagger实现。
• Swagger-js: 用于JavaScript的Swagger实现。
• Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
• Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
• Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

二、swagger使用

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>

2. 配置类

//标注这是一个配置类
@Configuration
//开启Swagger2的自动配置
@EnableSwagger2
public class SwaggerConfig {
	//通过docket来配置swagger的具体参数
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
			//配置文档信息
			.apiInfo(apiInfo())
			//配置扫描接口
			.select()
			//swagger搜索的包
			.apis(RequestHandlerSelectors.basePackage("com.hxh.xxx")) 
			//swagger路径匹配，这里使用的是any，所有路径。
			// none()任何请求都不扫描
			// regex(final String pathRegex)通过正则表达式控制 
			// ant(final String antPattern)通过ant()控制
			.paths(PathSelectors.any()) 
			.build();
	}
	//文档信息配置
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
			.title("标题")
			.description("描述")
			.version("版本version 1.0")
			.build();
		}
}

3. 常用注解

swagger通过在controller中，声明注解，API文档进行说明

• @Api()：用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源，参数如下：

  • tags：说明该类的作用，参数是个数组，可以填多个。
  • value=“该参数没什么意义，在UI界面上不显示，所以不用配置”
  • description = “用户基本信息操作”

• @ApiOperation()：用于方法，表示一个http请求访问该方法的操作，参数如下：

  • value=“方法的用途和作用”
  • notes=“方法的注意事项和备注”
  • tags：说明该方法的作用，参数是个数组，可以填多个。格式：tags={“作用1”,“作用2”}

• @ApiModel()：用于响应实体类上，用于说明实体作用，参数如下：

  • description=“描述实体的作用”

• @ApiModelProperty：用在属性上，描述实体类的属性，参数如下：

  • value=“用户名” 描述参数的意义
  • name=“name” 参数的变量名
  • required=true 参数是否必选

• @ApiImplicitParams：用在请求的方法上，包含多@ApiImplicitParam

• @ApiImplicitParam：用于方法，表示单独的请求参数，参数如下：

  • name=“参数ming”
  • value=“参数说明”
  • dataType=“数据类型”
  • paramType=“query” 表示参数放在哪里
    · header 请求参数的获取：@RequestHeader
    · query 请求参数的获取：@RequestParam
    · path（用于restful接口） 请求参数的获取： @PathVariable
    · body（不常用）
    · form（不常用）
  • defaultValue=“参数的默认值”
  • required=“true” 表示参数是否必须传

• @ApiParam()：用于方法，参数，字段说明 表示对参数的要求和说明，参数如下：

  • name=“参数名称”
  • value=“参数的简要说明”
  • defaultValue=“参数默认值”
  • required=“true” 表示属性是否必填，默认为false

• @ApiResponses：用于请求的方法上，根据响应码表示不同响应，一个@ApiResponses包含多个@ApiResponse

• @ApiResponse：用在请求的方法上，表示不同的响应，参数如下：

  • code=“404” 表示响应码(int型)，可自定义
  • message=“状态码对应的响应信息”

• @ApiIgnore()：用于类或者方法上，不被显示在页面上