Swagger3.0接口文档
使用:springBoot2.x + swagger3.0
1、pom引入
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2、yaml配置
server:
port: 8080
spring:
application:
name: ***医疗信息统计平台
#swagger配置
swagger:
enable: true
application-name: ${spring.application.name}
application-version: 1.0
application-description: zxd api info
3.创建配置类
package com.zxd.hospitalStage.config;
import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import org.w3c.dom.DocumentType;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Component
@EnableOpenApi
@ConfigurationProperties("swagger")
@Data
public class SwaggerConfiguration {
/**
* 是否开启Swagger,生产环境一般关闭,所以这里定义一个变量
**/
private Boolean enable;
/**
* 项目应用名
**/
private String applicationName;
/**
* 项目版本信息
**/
private String applicationVersion;
/**
* 项目描述信息
**/
private String applicationDescription;
/**
* 接口调试地址
**/
private String tryHost;
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30)
.pathMapping("/")
//定义是否开启swagger,false为关闭。可以通过变量控制,线上生产环境关闭
.enable(enable)
//配置api文档元信息
.apiInfo(apiInfo())
//选择那些接口作为swagger的doc发布
.select()
//apis() 控制那些接口暴露给swagger
//RequestHandlerSelectors.any() 所有都暴露
//RequestHandlerSelectors.basePackage("net.xdclass.*") 指定包位置
//RequestHandlerSelectors.withMethodAnnotation(ApiOpertion.class) 标记有这个注解 ApiOperation
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(applicationName)
.description(applicationDescription)
.contact(new Contact("信息统计平台", "https://baidu.com", "123456789@qq.com"))
.version(applicationVersion)
.build();
}
}
配置完,启动项目,访问
http://localhost:8080/swagger-ui/index.html
4、模块相关接口文档配置
4.1 参数配置
- @Api模块配置,用在controller类,描述接口
- @ApiOpertion接口配置,用在方法上,描述接口方法
- @ApiParam 方法参数配置,用在入参上面,描述参数
- @ApiIgnore 忽略此接口不生成文档
@RequestParam 入参
@Api(tags="医院数据展示模块",value = "医院controller")
@Slf4j
@CrossOrigin
@RequestMapping("/totalPatients")
@RestController
public class HospitalsConstroller {
....
@ApiOperation("数据展示")
@RequestMapping(value = "/detailsHospital", method = RequestMethod.POST)
public Result queryDetailHospital(
@ApiParam(name ="id",value="医院编号",example="0027")
@RequestParam (value="id",required = false, defaultValue = "0") String id) {
return null;
}
}
restful例子 @PathVariable
@Api(tags="医院数据展示模块",value = "医院controller")
@Slf4j
@CrossOrigin
@RequestMapping("/totalPatients")
@RestController
public class HospitalsConstroller {
....
@ApiOperation("数据展示")
@RequestMapping(value = "/detailsHospital/{id}", method = RequestMethod.POST)
public Result queryDetailHospital(
@ApiParam(name ="id",value="医院编号",example="0027")
@PathVariable int id) {
return null;
}
}
4.2 对象注解配置
- ApiModel 和ApiModelProperty对象注解介绍
- @ApiModel()
- 用于类 表示对类进行说明,用于参数进行实体类接收 ,value- 表示对象名 ,descripiton-描述
- 这种一般用在post创建的时候,使用对象提交这样的场景
- @ApiModelProperty()
- 用于方法,字段;表示对model属性说明或者数据操作更改
- value -字段说明
- name- 重写属性名字
- dataType- 重写属性类型
- required -是否必填
- example -举例说明
- hidden- 隐藏
**对象实体类QueryDetailHospitalVO **
@ApiModel(value = "请求区域内id对应的医院数据")
@Data
public class QueryDetailHospitalVO {
@ApiModelProperty(value = "开始时间",required = true,example = "2022/2/7")
@DateTimeFormat(pattern="yyyy/MM/dd")//前台 时间字符串类型转Date,注意时区 (前台 -> 后台)
@JsonFormat(pattern="yyyy/MM/dd",timezone = "GMT+8")
@NotNull(message = "开始时间不能为空")
private Date startTime;
@ApiModelProperty(value = "结束时间",required = true,example = "2022/2/8")
@DateTimeFormat(pattern="yyyy/MM/dd")//前台 时间字符串类型转Date,注意时区 (前台 -> 后台)
@JsonFormat(pattern="yyyy/MM/dd",timezone = "GMT+8")//后台 Date 类型转时间字符串,注意时区 (后台 -> 前台)
@NotNull(message = "结束时间不能为空")
private Date endTime;
@ApiModelProperty(value = "结束时间",required = true,example = "0028")
@NotNull(message = "请选择医院")
private String areacode;
}
@Api(tags="医院数据展示模块",value = "全部医院controller")
@Slf4j
@CrossOrigin
@RequestMapping("/totalPatients")
@RestController
public class HospitalsConstroller {
.....
@ApiOperation("心电影像检验查询")
@RequestMapping(value = "/detailsHospital", method = RequestMethod.POST)
public Result queryDetailHospital(@RequestBody @Validated QueryDetailHospitalVO detailVo) {
return null;
}
}
5、响应结果
- @ApiResponse 描述接口响应
@Api(tags="医院数据展示模块",value = "全部医院controller")
....
@RequestMapping("/totalPatients")
@RestController
public class HospitalsConstroller {
......
@ApiOperation("心电影像检验查询")
@RequestMapping(value = "/detailsHospital", method = RequestMethod.POST)
@ApiResponses({
@ApiResponse(responseCode = "400",description = "请求出错"),
@ApiResponse(responseCode = "403",description = "服务器拒绝请求"),
})
public Result queryDetailHospital(@RequestBody @Validated QueryDetailHospitalVO detailVo) {
return null;
}
}