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;
    }
}
  • 0
    点赞
  • 4
    收藏
    觉得还不错? 一键收藏
  • 3
    评论
Swagger 3.0 是一个用于构建、编写和管理 RESTful API 文档的工具。它提供了一种简单、易于理解和交互的方式来描述和测试 API,使开发者和客户端能够更好地了解和使用 API。Swagger 3.0 具有许多强大的功能,例如自动生成的 API 文档、交互式探索和调试界面、代码生成等等。 Swagger 3.0 的外网 Demo 可以是一个在线的展示页面,用于展示和测试一个特定的 RESTful API。在这个外网 Demo 中,用户可以看到该 API 的各个接口和其对应的请求参数、响应格式、请求方法等信息。同时,用户还可以在页面上进行接口的测试和调试,输入参数并查看对应的响应结果。 外网 Demo 的链接可以在 API 提供方的官方网站上找到。用户可以直接访问该链接,然后就可以开始使用 Swagger 3.0 的各项功能了。在 Demo 页面上,用户可以通过导航栏浏览 API 的各个接口,并查看每个接口的详细信息。用户还可以使用内置的测试界面进行请求参数的设置,并在发送请求后查看响应结果。 通过 Swagger 3.0 的外网 Demo,开发者和客户端可以更加直观地了解和使用 API。他们可以浏览 API 的各个接口,了解每个接口的功能和使用方法。同时,他们还可以通过 Demo 页面进行实际的测试和调试,验证 API 的正确性和稳定性。 总而言之,Swagger 3.0 的外网 Demo 是一个非常方便的工具,可以帮助开发者和客户端更好地了解和使用一个 RESTful API。它提供了简洁清晰的接口文档和交互式测试界面,使用户能够快速上手并使用 API。
评论 3
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值