1)简介
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是:
-
使得前后端分离开发更加方便,有利于团队协作
-
接口的文档在线自动生成,降低后端开发人员编写接口文档的负担
-
功能测试
Spring已经将Swagger纳入自身的标准,建立了Spring-swagger项目,现在叫Springfox。通过在项目中引入Springfox ,即可非常简单快捷的使用Swagger。
2)SpringBoot集成Swagger
引入依赖,在 study
-leadnews
模块中引入该依赖
<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文档技术会扫描指定的【Controller
】,而所有微服务都依赖了study
-leadnews-core-controller
,我们可以直接在该工程中实现对Swagger
的配置, 在study-leadnews-core-controller
工程的config包中添加一个配置类,代码如下:
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
/**
* 创建API文档信息
* @return
*/
@Bean
public Docket buildDocket() {
HashSet<String> strings = new HashSet<>();
strings.add("application/json");
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInfo())
//设置返回值数据类型为json
.produces(strings)
.select()
// 要扫描的API(Controller)基础包
.apis(RequestHandlerSelectors.basePackage("com.itheima"))
.paths(PathSelectors.any())
.build();
}
/**
* 定义Swagger文档信息
* @return
*/
private ApiInfo buildApiInfo() {
Contact contact = new Contact("黑马程序员","","");
return new ApiInfoBuilder()
.title("黑马头条-平台管理API文档")
.description("平台管理服务api")
.contact(contact)
.version("1.0.0").build();
}
}
3)Swagger常用注解
@Api:修饰整个类,描述Controller的作用
@ApiOperation:修饰类的一个方法 标识 操作信息 接口的定义
@ApiParam:单个参数的描述信息
@ApiModel:描述使用到的对象信息
@ApiModelProperty:描述使用到的对象的属性信息
@ApiResponse:HTTP1响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError:发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数的描述信息
我们在controller
中添加Swagger
注解,代码如下所示:
@Api(value = "频道管理", tags = "AdChannelController", description = "频道管理")
public class AdChannelController {}
在study-leadnews-admin-api
中和study-common
中【pojo
】中代码中添加【注解ApiModel
】和【ApiModelProperties
】如下:
AdChannel
:
@Data
@EqualsAndHashCode(callSuper = false)
@TableName("ad_channel")
@ApiModel(description = "频道",value="AdChannel")
public class AdChannel implements Serializable {
@ApiModelProperty(notes = "ID")
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
@ApiModelProperty(notes = "频道名字")
@TableField("name")
private String name;
@ApiModelProperty(notes = "频道描述")
@TableField("description")
private String description;
@ApiModelProperty(notes = "是否是默认频道")
@TableField("is_default")
private Integer isDefault;
@ApiModelProperty(notes = "状态")
@TableField("status")
private Integer status;
@ApiModelProperty(notes = "排序")
@TableField("ord")
private Integer ord;
@ApiModelProperty(notes = "创建时间")
@TableField("created_time")
private LocalDateTime createdTime;
}
分页查询请求条件封装对象:
@NoArgsConstructor
@AllArgsConstructor
@Data
@ApiModel(description = "分页请求对象",value="PageRequestDto")
public class PageRequestDto<T> implements Serializable {
//当前页码
@ApiModelProperty(notes = "当前页码")
private Long page = 1L;
//每页显示的行
@ApiModelProperty(notes = "每页显示的行")
private Long size = 10L;
//请求体实体对象
@ApiModelProperty(notes = "请求体条件对象")
private T body;
}
分页查询响应信息封装对象PageInfo
,代码如下:
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "通用分页查询返回响应结果对象", value = "PageInfo")
public class PageInfo<T> implements Serializable {
//当前页码
@ApiModelProperty(notes = "当前页")
private Long page;
//每页显示行
@ApiModelProperty(notes = "每页条数")
private Long size;
//总记录数
@ApiModelProperty(notes = "总记录数")
private Long total;
//总页数
@ApiModelProperty(notes = "总页数")
private Long totalPages;
//当前页记录
@ApiModelProperty(notes = "结果集")
private List<T> list;
}
官方的注解说明如下:掌握常见的即可
https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X
Swagger
文档虽然很好用,但是不支持离线文档,如果想支持离线文档,我们需要使用knife4j
,因为它功能更强大,支持离线文档。