OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程,目前版本是V3.0,并且已经发布并开源在github上。(https://github.com/OAI/OpenAPI-Specification) Swagger是全球最大的OpenAPI规范(OAS)API开发工具框架,支持从设计和文档到测试和部署的整个API生命周 期的开发。 (https://swagger.io/) Spring Boot 可以集成Swagger,生成Swagger接口,Spring Boot是Java领域的神器,它是Spring项目下快速构建项目的框架。
在Java类中添加Swagger的注解即可生成Swagger接口,常用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 | 默认值 |
1 在pom文件中添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
/**
* Swagger2配置类
* 在与spring boot集成时,放在与Application.java同级的目录下。
* 通过@Configuration注解,让Spring来加载该类配置。
* 再通过@EnableSwagger2注解来启用Swagger2。
*/
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
* basePackage要扫描的包
*
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xuecheng"))
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
* 访问地址:http://项目实际地址/swagger-ui.html
*
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXX api文档")
.description("XXX api文档")
// .termsOfServiceUrl("/")
.version("1.0")
.build();
}
}
在接口中添加swagger注解
@Api(value = "cms页面管理接口",description = "cms页面管理接口,提供页面的增 删 改 查")
public interface CmsPageControllerApi {
// 页面查询
@ApiOperation("分页查询列表")
@ApiImplicitParams({
@ApiImplicitParam(name="page",value="页码",required=true,paramType="path",dataType="int"),
@ApiImplicitParam(name="size",value="每页记录数",required=true,paramType="path",dataType="int")
})
public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest);
// 新增页面
@ApiOperation("新增页面")
public CmsPageResult add(CmsPage cmsPage);
}
Swagger接口生成工作原理:
1、系统启动,扫描到api工程中的Swagger2Configuration类
2、在此类中指定了包路径com.xuecheng,找到在此包下及子包下标记有@RestController注解的controller类
3、根据controller类中的Swagger注解生成接口文档。
启动项目工程,查看接口文档,请求:http://ip+端口/swagger-ui.html
4.使用swagger对接口进行测试
返回数据