Swagger3.0接口文档使用

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;
    }
}