怎么让百度搜索到自己的网站,深圳市住建工程交易,陕西 网站建设首选公司,找别人做网站要注意什么软件Swagger3 使用详解 一、简介1 引入依赖2 开启注解3 增加一个测试接口4 启动服务报错1.5 重新启动6 打开地址#xff1a;http://localhost:8093/swagger-ui/index.html 二、Swagger的注解1.注解Api和ApiOperation2.注解ApiModel和ApiModelProperty3.注解ApiImplicitParams和Api… Swagger3 使用详解 一、简介1 引入依赖2 开启注解3 增加一个测试接口4 启动服务报错1.5 重新启动6 打开地址http://localhost:8093/swagger-ui/index.html 二、Swagger的注解1.注解Api和ApiOperation2.注解ApiModel和ApiModelProperty3.注解ApiImplicitParams和ApiImplicitParam4.注解ApiResponses和ApiResponse5.注解ApiIgnore 三、Swagger的相关配置 一、简介
官方网站https://swagger.io/ Swagger 是一个开源的 API 开发和文档框架Swagger 旨在简化 RESTful API 的设计、开发、测试、文档化和消费过程。Swagger的出现节约了大量的后端人员对接接口的时间通过Swagger可以快速定义接口文档方便了前端后端的接口对接工作废话不多说直接上用例。 这里使用的SpringBoot 是2.6.11 版本
1 引入依赖
dependencygroupIdio.springfox/groupIdartifactIdspringfox-boot-starter/artifactIdversion3.0.0/version
/dependency2 开启注解
启动类增加注解
EnableSwagger2
// 或者使用下面的注解也是可以的
EnableOpenApi3 增加一个测试接口
增加一个接口方便看到Swagger帮我们生成的接口文档中的接口信息如下
package com.cheng.ebbing.message.controller;import com.cheng.ebbing.message.vo.UserVO;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** author pcc* version 1.0.0* description 测试接口*/
RestController
public class TestController {RequestMapping(value /test)public UserVO test(){return new UserVO(zhangsan,1234,1);}
}
4 启动服务报错
报错Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException 原因可以参考这篇文章 https://blog.csdn.net/weixin_45131680/article/details/131580270总结一句话就是SpringBoot2.6以上的版本整合Swagger2:3.0.0会碰到这个问题根本原因是路径匹配模式不适配。解决方案有两个他们的目的是为了更改路径匹配规则以适配Swagger2 的3.0 的版本。
解决方案一// 启动类增加了开启swagger注解的基础上增加以下注解
EnableWebMvc解决方案二 配置文件增加以下配置spring:mvc:pathmatch:matching-strategy: ant_path_matcher1.5 重新启动
选择上面其中一个方案进行解决即可然后重新启动就会正常了如下
6 打开地址http://localhost:8093/swagger-ui/index.html
到这里swagger的入门集成就成功了如果你没有设置项目的根路径那么Swagger的地址就是这个了如果设置了自行端口后增加根路径就行打开后如下图 界面里有四块信息是需要关注的。 左一展示的信息支持自定义可以用来标识文档的和服务的信息第四部分进行详细介绍 左二接口展示这里展示接口的详细信息最常用的地方,可以看到上面定义的测试接口已经在这里了第二部分详细介绍 左三这里展示我们再请求和响应中定义的实体信息比如上面接口的UserVO就在这里第二部分详细介绍 右一分组信息一般用于多个微服务时对不同微服务进行分组常用与和Gateway集成时对服务进行分组展示第三部分详细介绍
二、Swagger的注解
这里详细说下Swagger常用的注解根据使用频率来进行先后说明。这里分为了五个部分来说前四个部分都是分组来说的每组注解基本都是一起使用的所以就放一起来说也方便理解记忆。下面的前四组例子都将使用使用注解和不使用注解的方式来进行说明比对以此来方便了解注解的具体的作用。
1.注解Api和ApiOperation
这是使用频率最高的一组注解了。Api常用与接口类上用以对当前的接口类做整体声明。ApiOperation则用于接口方法上用以描述具体的方法真。 Api 正使用时其实只需要为Api声明tags标签即可其他的基本用不到如果需要再阅读下注解的源码即可value的值在源码描述中说是当tags不使用时会将其作为资源的描述但是笔者试了没啥用而且大家都是使用tags直接使用tags标签即可。假如存在下面两个方法他们的信息基本都是相同的一个使用了Api注解一个没有使用 // 使用了 Api注解的类
Api(tags 测试接口类1)
RestController
public class TestController1 {PostMapping(/test1Fun)public String test() {return test1;}
}// 未使用Api注解的类
RestController
public class TestController2 {PostMapping(/test2Fun)public String test() {return test2;}
}下面一起看下他们在Swagger中的展示区别吧注意重启生效 可以看到使用后多了汉字的描述这样对于文档使用者来说也就更为有好了这也就是tags属性的作用了其他属性基本不咋使用。 ApiOperation 这个注解则是使用在接口方法上的用以描述一个具体的接口它支持的所有属性都是和RequestMapping对应的因为他本来就是用来描述接口的和RequestMapping对应则是很好理解的。不过最常用的还是他的value属性用以简介当前的接口。其他用以描述接口的信息一般不设置也是可以看到的我们一般使用value属性简单描述接口的作用。 下面是一组使用ApiOperation和不使用的代码
// 使用注解ApiOperation
ApiOperation(测试接口1-方法1)
PostMapping(/test1Fun)
public String test() {return test1;
}// 不使用注解ApiOperation
PostMapping(/test2Fun)
public String test() {return test2;
}下面一起看下使用注解和不使用注解在Swagger中的区别
2.注解ApiModel和ApiModelProperty
这组注解是使用在实体上的一般前后端参数交互时都是使用Json数据进行交互Json交互时后端使用实体和注解RequestBody来接收前端传递的参数而这组注解则是用来描述实体的。实体既可以作为接收参数当然也可以作为返回参数。下面一起来看下。 ApiModel 被用于修饰实体类实体类可用于接口入参和返参一般只使用value属性即可。假设有如下两个实体信息一个加了ApiModel一个没有加 // 使用了注解ApiModel的注解
Data
ApiModel(用户实体1)
AllArgsConstructor
NoArgsConstructor
public class UserVO1 implements Serializable {private static final long serialVersionUID 1L;private String username;private String password;Integer id;
}// 不使用注解ApiModel
Data
AllArgsConstructor
NoArgsConstructor
public class UserVO2 implements Serializable {private static final long serialVersionUID 1L;private String username;private String password;Integer id;
}先看下使用了注解时的样子不使用则显示类名 下面是不使用的样子 此外在下面的位置也是可以看出区别的 ApiModelProperty 这个属性被用在实体的属性上用来标识实体属性的含义这个还是很有用的因为不用他来标识的话有些字段是人无法知道具体代表的含义的。这个也是基本使用value即可下面也是使用使用和不使用注解来比对下区别这里就只贴使用注解的代码了 Data
ApiModel(用户实体1)
AllArgsConstructor
NoArgsConstructor
public class UserVO1 implements Serializable {private static final long serialVersionUID 1L;ApiModelProperty(用户名)private String username;ApiModelProperty(用户密码)private String password;ApiModelProperty(用户ID)Integer id;
}下面是在swagger文章中看到的区别
3.注解ApiImplicitParams和ApiImplicitParam
上面一组注解被用于标识使用实体接收和返回的数据对象那么如果接受的数据不是json呢则需要别的注解来处理了这一组注解就可以实现这个功能。
参数传递大致有以下几种 1.使用body传递json后端使用注解RequestBody来接收2.使用body传递form-data后端使用注解RequestParam接收文件除外3.使用body传递x-www-form-urlencoded后端使用注解RequestParam接收4.使用path传参restful后端使用注解PathVariable来接收5.使用query传参即url传参后端使用注解RequestParam接收6.使用Cookie传参后端使用注解CookieValue接收
上面列举了集中数据的传递方式可以看到除了Json进行传递还有一些其他的数据传递此时ApiModel这组注解就无法满足我们的需要了那就只能使用ApiImplicitParams和ApiImplicitParam。上面的这些数据传递除了json都会在接口方法有参数进行映射。所以使用这组注解就都可以进行声明。这组注解和上面还有一点区别就是必须同时使用。
这里使用query传参进行说明吧。假设有如下接口代码
ApiOperation(测试接口1-方法1)
PostMapping(/test1Fun)
public UserVO1 test(RequestParam(name)String name) {return new UserVO1(用户1,1234,10);
}不使用注解时swagger展示如下 当添加了如下注解以后
ApiOperation(测试接口1-方法1)
PostMapping(/test1Fun)
ApiImplicitParams({ApiImplicitParam(name name,value 用户名,required true,paramType query,dataType String,dataTypeClass String.class)
})
public UserVO1 test(RequestParam(name)String name) {return new UserVO1(用户1,1234,10);
}swagger中展示如下 注意可以看到只是多了在注解ApiImplicitParam中描述的value其他都是相同的所以说其实使用这组注解时只需要关注ApiImplicitParam他的value就行了。不过需要注意的是这里还是用了注解RequestParamswagger文档中的required和query是这个注解赋予的如果没有这个注解swagger文档是不会有对应提示的。还有一点若是使用ApiImplicitParam的dataType则一定要使用dataTypeClass不然会一直提示warn日志
4.注解ApiResponses和ApiResponse
上一组注解时用来描述除了实体以外的入参的这个注解从字面看就知道是跟返回信息有关的先看下不加这个注解时的接口的返回在swagger中的展示 然后我们为接口增加这组注解如下 ApiOperation(测试接口1-方法1)PostMapping(/test1Fun)ApiResponses({ApiResponse(code 200, message 成功, response UserVO1.class,reference UserVO1),ApiResponse(code 400, message 失败,response UserVO1.class,reference UserVO1)})public UserVO1 test(RequestParam(name)String name) {return new UserVO1(用户1,1234,10);}下面是使用注解后的swagger文档展示 可以看到真正有作用的是code和message所以如果需要使用就使用这两个即可不过一把不使用这组注解因为后端服务一般不会抛出http的异常码而是通过实体的错误码来标识响应信息。
5.注解ApiIgnore
这个注解也比较简单可以使用在类或者方法上都是可以的用以将其排除排除后swagger不会将其加入文档。 假如有如下代码 ApiIgnoreApiOperation(测试接口1-方法1)PostMapping(/test1Fun)ApiResponses({ApiResponse(code 200, message 成功, response UserVO1.class,reference UserVO1),ApiResponse(code 400, message 失败,response UserVO1.class,reference UserVO1)})public UserVO1 test(RequestParam(name)String name) {return new UserVO1(用户1,1234,10);}因为加了该注解我们再swagger中是看不到的
三、Swagger的相关配置
其实不添加任何配置不影响使用但知道配置方便我们更好地针对自己的特别需求进行定制化。所以配置还是需要进行了解和熟悉的。比如生产上是不推荐打开swagger的因为有很大的安全隐患。下面一起说下注意这些配置信息都需要放在配置文件这里为了方便都直接写死了。
package com.cheng.ebbing.message;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;/*** author pcc* version 1.0.0* description swagger3配置类*/
EnableWebMvc // 适配springboot2.6和swagger3
EnableOpenApi // 开启swagger3
Configuration
public class config {Beanpublic Docket createRestApi(){return new Docket(DocumentationType.OAS_30).enable(true) // 开启swagger生产建议关闭.apiInfo(apiInfo()) // 配置文档的基础信息.groupName(这是分组名)// 不设置默认都是default单个服务可以不使用分组如果想要多个分组再来个Docket设置组名即可.select() // 开始配置路径相关信息// 扫描固定包其他包下的信息不回出现在swagger.apis(RequestHandlerSelectors.basePackage(com.cheng.ebbing))// 扫描所有有注解的api用这种方式更灵活,也可以扫描指定的接口,支持通配符.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {// 配置文档的基础信息例如标题、描述等return new ApiInfoBuilder().title(这是title).description(这是description).license(这是license).licenseUrl(这是licenseUrl).termsOfServiceUrl(这是termsOfServiceUrl).contact(new Contact(concat-name,concat-url,concat-email)).version(版本1.0.0).build();}
}
增加完配置信息以后swagger文档展示如下 这些配置信息注意不要直接写死而应该从配置文件获取这里直接写死只是为了演示使用swagger只是项目辅助的小框架就只说到这里了。
