时间:2021-05-20
Swagger的介绍
🔶你可能尝试过写完一个接口后,自己去创建接口文档,或者修改接口后修改接口文档。多了之后,你肯定会发生一个操作,那就是忘记了修改文档或者创建文档(除非你们公司把接口文档和写接口要求得很紧密😓忘记写文档就扣工资?,否则两个分离的工作总是有可能遗漏的)。而swagger就是一个在你写接口的时候自动帮你生成接口文档的东西,只要你遵循它的规范并写一些接口的说明注解即可。
优点与缺点
🔶优点:
🔶缺点:
😓上面的缺点好像写的有点多,你可能会觉得swagger这个坑有点大。但其实主要是规范问题,而规范问题有时候又会提高你的代码规范性,这个就见仁见智了,你以前可能什么接口的参数都使用一个类,而现在swagger要求你分开后,某种层次上提高了你的代码规范性。
🔶注:以下代码示例基于Spring Boot。完整代码可以参考:swagger-demo
添加swagger
💡这里先讲添加swagger,也就是先整合进来,至于怎么使用,下面的“场景”中再讲解。
1.添加依赖包:
❗注意,这里的前提是已经导入了spring boot的web包。
<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>2.配置Swagger:
要使用swagger,我们必须对swagger进行配置,我们需要创建一个swagger的配置类,比如可以命名为SwaggerConfig.java
package com.example.config;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration // 标明是配置类@EnableSwagger2 //开启swagger功能public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的,代表swagger2// .groupName("分布式任务系统") // 如果配置多个文档的时候,那么需要配置groupName来分组标识 .apiInfo(apiInfo()) // 用于生成API信息 .select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档 .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用于指定扫描哪个包下的接口 .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档,可以配置这里 .build(); } /** * 用于定义API主界面的信息,比如可以声明所有的API的总标题、描述、版本 * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("XX项目API") // 可以用来自定义API的主标题 .description("XX项目SwaggerAPI管理") // 可以用来描述整体的API .termsOfServiceUrl("") // 用于定义服务的域名 .version("1.0") // 可以用来定义版本。 .build(); // }}3.测试
运行我们的Spring Boot项目,(我默认是8080端口,如果你不一样,请注意修改后续的url),访问http://localhost:8080/swagger-ui.html
然后你就可以看到一个如下的界面,由于我们暂时没有配置接口数据,所以下面显示No operations defined in spec!
💡下面我们将介绍如何定义接口,以及在swagger UI界面中的内容。
场景:
定义接口组
接口有时候应该是分组的,而且大部分都是在一个controller中的,比如用户管理相关的接口应该都在UserController中,那么不同的业务的时候,应该定义/划分不同的接口组。接口组可以使用@Api来划分。
比如:
和
@Api(tags = "用户管理") // tags:你可以当作是这个组的名字。@RestControllerpublic class UserController {}🔵你也可以理解成基于tags来分组,就好像一些文章里面的标签一样,使用标签来分类。
🔵如果这个Controller下(接口组)下面没有接口,那么在swagger ui中是不会显示的,如果有的话就会这样显示:
定义接口
使用了@Api来标注一个Controller之后,如果下面有接口,那么就会默认生成文档,但没有我们自定义的说明:
@Api(tags = "用户管理")@RestControllerpublic class UserController { // 注意,对于swagger,不要使用@RequestMapping, // 因为@RequestMapping支持任意请求方式,swagger会为这个接口生成7种请求方式的接口文档 @GetMapping("/info") public String info(String id){ return "aaa"; }}我们可以使用@ApiOperation来描述接口,比如:
@ApiOperation(value = "用户测试",notes = "用户测试notes") @GetMapping("/test") public String test(String id){ return "test"; }常用配置项:
定义接口请求参数
上面使用了@ApiOperation来了描述接口,但其实还缺少接口请求参数的说明,下面我们分场景来讲。
🔵注意一下,对于GET方式,swagger不推荐使用body方式来传递数据,也就是不希望在GET方式时使用json、form-data等方式来传递,这时候最好使用路径参数或者url参数。(😓虽然POSTMAN等是支持的),所以如果接口传递的数据是json或者form-data方式的,还是使用POST方式好。
场景一:请求参数是实体类。
此时我们需要使用@ApiModel来标注实体类,然后在接口中定义入参为实体类即可:
@ApiModel:用来标类
常用配置项:
value:实体类简称
description:实体类说明
@ApiModelProperty:用来描述类的字段的意义。
常用配置项:
value:字段说明
example:设置请求示例(Example Value)的默认值,如果不配置,当字段为string的时候,此时请求示例中默认值为"".name:用新的字段名来替代旧的字段名。
allowableValues:限制值得范围,例如{1,2,3}代表只能取这三个值;[1,5]代表取1到5的值;(1,5)代表1到5的值,不包括1和5;还可以使用infinity或-infinity来无限值,比如[1, infinity]代表最小值为1,最大值无穷大。
required:标记字段是否必填,默认是false,
hidden:用来隐藏字段,默认是false,如果要隐藏需要使用true,因为字段默认都会显示,就算没有@ApiModelProperty。
// 先使用@ApiModel来标注类@ApiModel(value="用户登录表单对象",description="用户登录表单对象")public class LoginForm { // 使用ApiModelProperty来标注字段属性。 @ApiModelProperty(value = "用户名",required = true,example = "root") private String username; @ApiModelProperty(value = "密码",required = true,example = "123456") private String password; // 此处省略入参赋值时需要的getter,setter,swagger也需要这个}定义成入参:
@ApiOperation(value = "登录接口",notes = "登录接口的说明") @PostMapping("/login") public LoginForm login(@RequestBody LoginForm loginForm){ return loginForm; }效果:
场景二:请求参数是非实体类。
(再说一次:对于GET方式,swagger不推荐使用body方式来传递数据,所以虽然Spring MVC可以自动封装参数,但对于GET请求还是不要使用form-data,json等方式传递参数,除非你使用Postman来测试接口,swagger在线测试是不支持这个操作的)
对于非实体类参数,可以使用@ApiImplicitParams和@ApiImplicitParam来声明请求参数。
@ApiImplicitParams用在方法头上,@ApiImplicitParam定义在@ApiImplicitParams里面,一个@ApiImplicitParam对应一个参数。
@ApiImplicitParam常用配置项:
💡方法三:使用@ApiImplicitParams来额外标注一个请求头参数,例如:
// 如果需要额外的参数,非本方法用到,但过滤器要用,类似于权限token @PostMapping("/login6") @ApiOperation(value = "带token的接口",notes = "带token的接口") @ApiImplicitParams({ @ApiImplicitParam(name = "authorization",//参数名字 value = "授权token",//参数的描述 required = true,//是否必须传入 paramType = "header" ) , @ApiImplicitParam(name = "username",//参数名字 value = "用户名",//参数的描述 required = true,//是否必须传入 paramType = "query" ) }) public String login6(String username){ return username; }Swagger的安全管理
1.如果你整合了权限管理,可以给swagger加上权限管理,要求访问swagger页面输入用户名和密码,这些是spring security和shiro的事了,这里不讲。
2.如果你仅仅是不想在正式环境中可以访问,可以在正式环境中关闭Swagger自动配置,这就不会有swagger页面了。使用@Profile({"dev","test"})注解来限制只在dev或者test下启用Swagger自动配置。
然后在Spring Boot配置文件中修改当前profilespring.profiles.active=release,重启之后,此时无法访问http://localhost:8080/swagger-ui.html
到此这篇关于Spring Boot整合swagger使用教程的文章就介绍到这了,更多相关Spring Boot整合swagger内容请搜索以前的文章或继续浏览下面的相关文章希望大家以后多多支持!
声明:本页内容来源网络,仅供用户参考;我单位不保证亦不表示资料全面及准确无误,也不保证亦不表示这些资料为最新信息,如因任何原因,本网内容或者用户因倚赖本网内容造成任何损失或损害,我单位将不会负任何法律责任。如涉及版权问题,请提交至online#300.cn邮箱联系删除。
前言本篇文章主要介绍的是SpringBoot整合Swagger(API文档生成框架)和SpringBoot整合Actuator(项目监控)使用教程。Spring
在使用spring-boot开发的时候,我们很多时候会使用swagger作为api文档输出。可以在UI界面上看到api的路径,参数等等。当然,作为开发环境是很方
前期工作1.导入mybatis整合依赖org.mybatis.spring.bootmybatis-spring-boot-starter2.1.42.连接数据
本文介绍了springboot的maven配置依赖详解,分享给大家,具体如下:我们通过引用spring-boot-starter-parent,添加spring
sprig-boot是一个微服务架构,加快了spring工程快速开发,以及简便了配置。接下来开始spring-boot与mybatis的整合。1、创建一个mav