swagger使用

pom依赖 

io.springfoxspringfox-swagger2io.springfoxspringfox-swagger-ui

com.xuecheng.api.config.Swagger2Configuration.java

package com.xuecheng.api.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;//
&＃64;Configuration
&＃64;EnableSwagger2
public class Swagger2Configuration {&＃64;Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.xuecheng")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("学成网api文档").description("学成网api文档")
// .termsOfServiceUrl("/").version("1.0").build();}}

&＃64;RestController 

启动   http://localhost:31001/swagger-ui.html 

固定格式  地址后加:swagger-ui.html 

补充: 

1.Swagger介绍
OpenAPI规范&＃xff08;OpenAPI Specification 简称OAS&＃xff09;是Linux基金会的一个项目&＃xff0c;试图通过定义一种用来描述API格
式或API定义的语言&＃xff0c;来规范RESTful服务开发过程&＃xff0c;目前版本是V3.0&＃xff0c;并且已经发布并开源在github上。
&＃xff08;https://github.com/OAI/OpenAPI-Specification&＃xff09;
Swagger是全球最大的OpenAPI规范&＃xff08;OAS&＃xff09;API开发工具框架&＃xff0c;支持从设计和文档到测试和部署的整个API生命周
期的开发。 (https://swagger.io/)
Spring Boot 可以集成Swagger&＃xff0c;生成Swagger接口&＃xff0c;Spring Boot是Java领域的神器&＃xff0c;它是Spring项目下快速构建
项目的框架

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

&＃64;ApiImplicitParam属性&＃xff1a;

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

3.Swagger接口定义
修改接口工程中页面查询接口&＃xff0c;添加Swagger注解。

&＃64;Api(value&＃61;"cms页面管理接口",description &＃61; "cms页面管理接口&＃xff0c;提供页面的增、删、改、查")
public interface CmsPageControllerApi {
&＃64;ApiOperation("分页查询页面列表")
&＃64;ApiImplicitParams({
&＃64;ApiImplicitParam(name&＃61;"page",value &＃61; "页
码",required&＃61;true,paramType&＃61;"path",dataType&＃61;"int"),
&＃64;ApiImplicitParam(name&＃61;"size",value &＃61; "每页记录
数",required&＃61;true,paramType&＃61;"path",dataType&＃61;"int")
})
public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest) ;
}

在QueryPageRequest类中使用注解 ApiModelProperty 对属性注释&＃xff1a;

&＃64;Data
public class QueryPageRequest extends RequestData {
//站点id
&＃64;ApiModelProperty("站点id")
private String siteId;
//页面ID
&＃64;ApiModelProperty("页面ID")
private String pageId;
//页面名称
&＃64;ApiModelProperty("页面名称")
private String pageName;
//页面别名
&＃64;ApiModelProperty("页面别名")
private String pageAliase;
//模版id
&＃64;ApiModelProperty("模版id")
private String templateId;
}

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

点击“分页查询页面列表”&＃xff0c;打开接口

使用Swagger工具测试服务接口&＃xff1a;
1&＃xff09;在cms服务接口中打断点
2&＃xff09;打开接口文档页面&＃xff0c;输入请求参数&＃xff0c;点击“Try it out”发起请求。