Swagger入门

Swagger介绍

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。Spring Boot 可以集成Swagger，生成Swagger接口，Spring Boot是Java领域的神器，它是Spring项目下快速构建项目的框架。

Swagger常用注解

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

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

Swagger接口定义

@Api(value="用户管理接口",description = "用户管理接口，提供用户的CRUD")
public interface UserService {

	@ApiOperation("分页查询列表")
	@ApiImplicitParams({
	@ApiImplicitParam(name="page",value = "页码",
	required=true,paramType="path",dataType="int"),
	@ApiImplicitParam(name="size",value = "每页记录数",
	required=true,paramType="path",dataType="int")
	@ApiImplicitParam(name="pageRequest",value = "分页对象",
	required=true,paramType="path",dataType="PageRequest")
	})
	public ActionResult findList(int page, int size, PageRequest pageRequest);
}

	@Data
	public class User{
	//页面ID
	@ApiModelProperty("用户ID")
	private String id;
	//页面名称
	@ApiModelProperty("用户名称")
	private String userName;
	}

Swagger接口查看

Swagger接口生成工作原理：
1、系统启动，扫描到api工程中的Swagger2Configuration类
2、在此类中指定了包路径com.xuecheng，找到在此包下及子包下标记有@RestController注解的controller类
3、根据controller类中的Swagger注解生成接口文档。
启动cms服务工程，查看接口文档，请求：http://localhost:port/swagger-ui.html