大型医疗挂号微服务“马上好医”医疗项目(5)Swagger的使用

2024-05-07 13:20

本文主要是介绍大型医疗挂号微服务“马上好医”医疗项目(5)Swagger的使用,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

Swagger的简单介绍

Swagger 是一个 RESTful 接口文档的规范和工具集,它的目标是统一 RESTful 接口文档的格式和规范。在开发过程中,接口文档是非常重要的一环,它不仅方便开发者查看和理解接口的功能和参数,还能帮助前后端开发协同工作,提高开发效率。在 Spring Boot 中,我们可以通过集成 Swagger 来实现接口文档的自动生成。Swagger 通过注解来描述接口,然后根据这些注解自动生成接口文档。

同类型的产品

ApiDoc:

ApiDoc定位: ApiDoc=Postman+Swagger+mock+Jmeter,是一款集 API设计,接口文档管理、代码生成、API 调试、API mock,API 自动化为一体的接口一站式协作平台。

也就是说,它比 swagger 的的功能要更加广泛和齐全,不仅通过可视化界面设计接口生成接口文档和项目代码,

还打通了接口数据的协作流程,一套接口数据,设计出来可以给前端、测试使用,减少了再不同系统间切换、导入导出数据、更新维护的麻烦。

缺点:太繁琐,因为支持了太多的功能,并且也不符合注解式开发的规范,需要写大量的文档类东西。

Swagger的简单上手:

依赖:

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

配置:

Swagger是通过配置类的方式来添加配置的

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("接口文档").description("接口文档").version("1.0.0").build();}
}

注解:

  • @Api:用于描述接口的类或接口
  • @ApiOperation:用于描述接口的方法
  • @ApiParam:用于描述接口的参数
  • @ApiModel:用于描述数据模型
  • @ApiModelProperty:用于描述数据模型的属性
  • @ApiImplicitParams:方法参数的说明
  • @ApiImplicitParam:用于指定单个参数的说明
  • @ApiResponses:方法返回值的说明
  • @ApiResponse:用于指定单个参数的说明

注解属性:

  • value:url的路径值
  • tags :如果设置这个值、value的值会被覆盖
  • description:对api资源的描述
  • basePath:基本路径
  • position:如果配置多个Api 想改变显示的顺序位置
  • produces :“application/json, application/xml”
  • consumes:“application/json, application/xml”
  • protocols : http, https, ws, wss.
  • authorizations: 高级特性认证时配置
  • hidden :配置为true ,将在文档中隐藏

查看接口文档

启动 Spring Boot 应用后,我们可以在浏览器中访问http://localhost:8080/swagger-ui.html来查看接口文档。在 Swagger UI 页面中,我们可以看到所有的接口信息,包括接口名称、请求方式、请求路径、请求参数、响应参数等。

Swagger的用法:

1、描述数据模型

我们可以使用 @ApiModel 和 @ApiModelProperty 注解来描述数据模型和属性。例如,我们可以编写一个 User 类,并在类上使用 @ApiModel 和

@ApiModelProperty 注解来描述该数据模型:@ApiModel(description = "用户信息")
public class User {@ApiModelProperty(value = "用户 ID", example ="1") private Long id;@ApiModelProperty(value = "用户名", example = "张三")private String username;@ApiModelProperty(value = "密码", example = "123456")private String password;// 省略 getter 和 setter 方法
}

在上面的代码中,@ApiModel 表示该类是一个数据模型,@ApiModelProperty 表示该属性是数据模型的一个属性,value 属性表示属性的描述,example 属性表示属性的示例值。

2、描述枚举类型

我们可以使用 @ApiModel 和 @ApiModelProperty 注解来描述枚举类型。例如,我们可以编写一个 Gender 枚举类型,并在枚举值上使用 @ApiModelProperty 注解来描述该枚举值:

@ApiModel(description = "性别") public enum Gender {@ApiModelProperty(value = "男")
MALE,@ApiModelProperty(value = "女")
FEMALE;
}

在上面的代码中,@ApiModel 表示该枚举类型是一个描述性别的枚举类型,@ApiModelProperty 表示该枚举值是描述男性的枚举值或描述女性的枚举值。

3、描述响应参数

我们可以使用 @ApiResponses 和 @ApiResponse 注解来描述接口的响应参数。例如,我们可以编写一个 getUserById() 方法,并在方法上使用 @ApiResponses 和 @ApiResponse 注解来描述该方法的响应参数:

@GetMapping("/user/{id}")
@ApiOperation(value = "根据 ID 获取用户信息") 
@ApiResponses({ @ApiResponse(code = 200, message = "请求成功", response = User.class), 
@ApiResponse(code = 404, message = "用户不存在") }) 
public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id) 
{ // 根据 ID 查询用户信息 
}

在上面的代码中,@ApiResponses 表示该方法的响应参数,@ApiResponse 表示该响应参数的描述,code 属性表示响应码,message 属性表示响应消息,response 属性表示响应的数据模型。

五、Swagger 的进阶使用

1、配置全局参数

我们可以在配置类中使用 globalOperationParameters() 方法来配置全局参数。例如,我们可以配置一个全局的 Authorization 参数,用于授权:

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().globalOperationParameters(Arrays.asList(new ParameterBuilder().name("Authorization").description("授权").modelRef(new ModelRef("string")).parameterType("header").required(false).build())).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("接口文档").description("接口文档").version("1.0.0").build();}}

在上面的代码中,我们通过 globalOperationParameters() 方法来配置一个全局的 Authorization 参数,用于授权。

2、配置安全协议

我们可以在配置类中使用 securitySchemes() 方法来配置安全协议。例如,我们可以配置一个 Bearer Token 安全协议:

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().securitySchemes(Arrays.asList(new ApiKey("Bearer", "Authorization", "header"))).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("接口文档").description("接口文档").version("1.0.0").build();}}

在上面的代码中,我们通过 securitySchemes() 方法来配置一个 Bearer Token 安全协议。

3、配置安全上下文

我们可以在配置类中使用 securityContexts() 方法来配置安全上下文。例如,我们可以配置一个安全上下文,用于在 Swagger UI 中显示认证按钮:

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().securitySchemes(Arrays.asList(new ApiKey("Bearer", "Authorization", "header"))).securityContexts(Collections.singletonList(SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("Bearer", new AuthorizationScope[0]))).build())).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("接口文档").description("接口文档").version("1.0.0").build();}}

在上面的代码中,我们通过 securityContexts() 方法来配置一个安全上下文,用于在 Swagger UI 中显示认证按钮。

4、配置忽略参数

在接口中,有些参数可能是敏感信息,我们不希望在接口文档中显示。我们可以使用 @ApiIgnore 注解来忽略这些参数。例如,我们可以在 User 类中使用 @ApiIgnore 注解来忽略密码参数:

@ApiModel(description = "用户信息")
public class User {@ApiModelProperty(value = "用户 ID", example = "1")private Long id;@ApiModelProperty(value = "用户名", example = "张三")private String username;@ApiModelProperty(hidden = true)@ApiIgnoreprivate String password;// 省略 getter 和 setter 方法
}

在上面的代码中,@ApiModelProperty(hidden = true) 表示该参数是隐藏的,@ApiIgnore 表示忽略该参数。

六、总结

通过集成 Swagger,我们可以方便地生成接口文档,使得前后端开发协同更加高效。在使用 Swagger 时,我们需要注意以下几点:

  • 使用注解来描述接口信息,包括接口名称、请求方式、请求路径、请求参数、响应参数等;
  • 在配置类中配置 Swagger,包括扫描的包路径、接口文档信息、全局参数、安全协议、安全上下文等;
  • 描述数据模型、枚举类型、响应参数等信息,方便开发者查看和理解接口的功能和参数;
  • 在需要时使用 @ApiIgnore 注解来忽略敏感参数的显示。
  • 最后,需要注意的是,Swagger 只是一种规范和工具集,它并不能取代单元测试和集成测试等其他测试方式。在开发过程中,我们需要综合使用各种测试方式,保证软件的质量和稳定性。

这篇关于大型医疗挂号微服务“马上好医”医疗项目(5)Swagger的使用的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/967469

相关文章

如何使用 Python 读取 Excel 数据

《如何使用Python读取Excel数据》:本文主要介绍使用Python读取Excel数据的详细教程,通过pandas和openpyxl,你可以轻松读取Excel文件,并进行各种数据处理操... 目录使用 python 读取 Excel 数据的详细教程1. 安装必要的依赖2. 读取 Excel 文件3. 读

SpringBoot基于配置实现短信服务策略的动态切换

《SpringBoot基于配置实现短信服务策略的动态切换》这篇文章主要为大家详细介绍了SpringBoot在接入多个短信服务商(如阿里云、腾讯云、华为云)后,如何根据配置或环境切换使用不同的服务商,需... 目录目标功能示例配置(application.yml)配置类绑定短信发送策略接口示例:阿里云 & 腾

SpringBoot项目中报错The field screenShot exceeds its maximum permitted size of 1048576 bytes.的问题及解决

《SpringBoot项目中报错ThefieldscreenShotexceedsitsmaximumpermittedsizeof1048576bytes.的问题及解决》这篇文章... 目录项目场景问题描述原因分析解决方案总结项目场景javascript提示:项目相关背景:项目场景:基于Spring

解决Maven项目idea找不到本地仓库jar包问题以及使用mvn install:install-file

《解决Maven项目idea找不到本地仓库jar包问题以及使用mvninstall:install-file》:本文主要介绍解决Maven项目idea找不到本地仓库jar包问题以及使用mvnin... 目录Maven项目idea找不到本地仓库jar包以及使用mvn install:install-file基

Python使用getopt处理命令行参数示例解析(最佳实践)

《Python使用getopt处理命令行参数示例解析(最佳实践)》getopt模块是Python标准库中一个简单但强大的命令行参数处理工具,它特别适合那些需要快速实现基本命令行参数解析的场景,或者需要... 目录为什么需要处理命令行参数?getopt模块基础实际应用示例与其他参数处理方式的比较常见问http

C 语言中enum枚举的定义和使用小结

《C语言中enum枚举的定义和使用小结》在C语言里,enum(枚举)是一种用户自定义的数据类型,它能够让你创建一组具名的整数常量,下面我会从定义、使用、特性等方面详细介绍enum,感兴趣的朋友一起看... 目录1、引言2、基本定义3、定义枚举变量4、自定义枚举常量的值5、枚举与switch语句结合使用6、枚

使用Python从PPT文档中提取图片和图片信息(如坐标、宽度和高度等)

《使用Python从PPT文档中提取图片和图片信息(如坐标、宽度和高度等)》PPT是一种高效的信息展示工具,广泛应用于教育、商务和设计等多个领域,PPT文档中常常包含丰富的图片内容,这些图片不仅提升了... 目录一、引言二、环境与工具三、python 提取PPT背景图片3.1 提取幻灯片背景图片3.2 提取

springboot项目如何开启https服务

《springboot项目如何开启https服务》:本文主要介绍springboot项目如何开启https服务方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教... 目录springboot项目开启https服务1. 生成SSL证书密钥库使用keytool生成自签名证书将

使用Python实现图像LBP特征提取的操作方法

《使用Python实现图像LBP特征提取的操作方法》LBP特征叫做局部二值模式,常用于纹理特征提取,并在纹理分类中具有较强的区分能力,本文给大家介绍了如何使用Python实现图像LBP特征提取的操作方... 目录一、LBP特征介绍二、LBP特征描述三、一些改进版本的LBP1.圆形LBP算子2.旋转不变的LB

Maven的使用和配置国内源的保姆级教程

《Maven的使用和配置国内源的保姆级教程》Maven是⼀个项目管理工具,基于POM(ProjectObjectModel,项目对象模型)的概念,Maven可以通过一小段描述信息来管理项目的构建,报告... 目录1. 什么是Maven?2.创建⼀个Maven项目3.Maven 核心功能4.使用Maven H