怀化建设局网站icp查询官网

当前位置： 首页 > news >正文

怀化建设局网站,icp查询官网,河南做网站优化,wordpress 抓取微信文章目录一、swagger2 简介背景Open API ???swagger2的作用swagger2常用工具组件#xff1a;二、Springfox三、springBoot使用swagger2#xff08;简单示例#xff09;四、Swagger-UI使用五、配置文件1、配置类#xff1a;给docket上下文配置api描述信息2、配置类#… 文章目录一、swagger2 简介背景Open API ???swagger2的作用swagger2常用工具组件二、Springfox三、springBoot使用swagger2简单示例四、Swagger-UI使用五、配置文件1、配置类给docket上下文配置api描述信息2、配置类扫描包3、自定义注解设置不需要生成接口文档的方法▶Target-描述当前的注解可以定义在什么资源上▶Retention-当前注解在什么时候有效▶示例4、配置路径范围配置paths()六、Swagger2常用注解常用注解ApiApiOperationApiParamApiImplicitParam-sApiModel、ApiModelProperty一、swagger2 简介 官网https://swagger.io/ 背景 我们后端在编写项目的时候往往都会在代码上加上注释方便自己以后的修改和维护和方便别人的理解。但是对对前后端分离的项目前端人员写前端代码后端人员编写后端的代码。这样的话当前端需要调用我们后端的接口的时候就会来找我们询问参数以及请求的接口路径。如果每次都来问的话就会很繁琐。所以我们要讲我们自己编写的代码生成一个api文档里面描述了我们各种接口调用规则我们只需要将这个api文档交给前端人员即可。前端人员就可以根据我们提供的文档获取到他们需要调用的接口路径以及参数信息。 Open API ??? Open API规范(OpenAPI Specification)以前叫做Swagger规范是RESTAPI的API描述格式。 Open API文件允许描述整个API包括: 每个访问地址的类型。POST 或GET。I每个操作的参数。包括输入输出参数。·认证方法。连接信息声明使用团队和其他信息。 Open API规范可以使用YAML或JSON格式进行编写。这样更利于我们和机器进行阅读。 swagger2的作用 swagger2 是一个规范和完整的框架用于生成、描述、调用和可视化Restful风格的web服务 作用 接口的文档在线自动生成功能测试 用白话说就是后端人员写完代码后不想写开发文档就嵌用api注解代码启动访问固定的路径 ip端口路径地址来访问代码。 swagger2常用工具组件 1、Swagger Editor基于浏览器编辑器可以在里面编写Open API规范。类似 Markdown具有实时预览描述文件的功能。还要自己写需要会json或者yaml 2、Swagger UI将Open API规范呈现为交互式API文档。用可视化U展示描述文件。注解 3、Swagger Codegen将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和 cwiki形式的接口文档同时也可以生成多种 言语的客户端和服务端代码。 4、Swagger Hub集成了上面所有项月的各个功能你可以以项目和版本为单位将你 的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作 需要注册账号分免费版和收费版。 二、Springfox 使用Swagger时如果碰见版本更新或迭代时只需要更改Swagger的描述文件即可。 但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件( yml或json )也是一种负担就直接改代码这样开发文档的作用就没意义了。 作用 Spring-fox是根据代码生成接口文档所以正常的进行更新项目版本修改代码即可 而不需要跟随修改描述文件。 Spring-fox利用自身AOP 特性把 Swagger集成进来底层还是Swagger。但是使 用起来确方便很多。所以实际开发中使用springfox。 官网http://springfox.github.io/springfox/ 源码https://github.com/springfox/springfox 三、springBoot使用swagger2简单示例 ▶导入依赖pom.xml自己库里的其他版本都行 !–swagger2的依赖–dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version/dependency!–视图逻辑swagger-ui–dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/versionscopecompile/scope/dependency▶先写一个controller里面有三种请求方法自定义、get、post RestController//方法中所有的返回值都相当于加了一个ResponseBody RequestMapping(/user) public class MyController {PostMapping(/getUserById)//post请求public String post(Integer id){return post:根据id获取User;}GetMapping(/getUsers)//get请求public String get(){return get:获取所有的User;}RequestMapping(/req)//这种请求方式是不限制请求方式的任意请求方式都可以访问public String req(String m){return request;} }▶在启动类上注解EnableSwagger2 EnableSwagger2 springfox提供的注解代表swagger2相关技术开启会扫描当前类所在包及子包中所有的类型中的注解, ▶运行启动类访问路径http://localhost:8080/swagger-ui.html 访问swagger-ui.html后可以在页面中着到所有需要生成接口文档的控制器名称 basic-error-controller中是springBoot内部的关于错误提示的controller。MyController自己写的。其中有get和post的请求还有一个没有限制请求方式的方法。…… 四、Swagger-UI使用 【扫描我们编写的所有的控制器扫描约束显示在视图中上面截图】 GetMapping(/get) 这两个方法是等价的 RequestMapping(method {RequestMethod. GET})Swagger-UI: 显示控制器显示控制器中的请求方法路径地址的处理、参数、名字等简单测试请求以及返回的响应结果描述 五、配置文件 上面提到过在视图中有些东西可以修改与本项目的内容无关就需要通过配置类来实现修改
1、配置类给docket上下文配置api描述信息 Configuration public class SwaggerConfig1 {/*** 创建Docket类型的对象。并使用spring容器管理。* Docket是Swagger中的全局配置对象。* return docket/Beanpublic Docket createRestApi() {Docket docket new Docket(DocumentationType.SWAGGER_2);//API帮助文档的描述信息ApiInfo apiInfo new ApiInfoBuilder().contact( //配置swagger文档主体内容new Contact(简单示例Swagger的开发文档, //是文档的发布者名称http://www/xxxx, //是文档发布者的网站地址。企业网站adminbjsxt.com) //文档发布者的电子邮箱).title(swagger文档标题).description(swagger2 是一个规范和完整的框架用于生成、描述、调用和可视化Restful风格的web服务,开发帮助文档).version(1.1).build();docket.apiInfo(apiInfo);return docket;} }文档运行路径http://localhost:8080/swagger-ui.html对比上张图观察上下文配置api描述信息都是修改的文档的哪个地方。
2、配置类扫描包 docket.select() //获取Docket中的选择器。返回ApiSelectorBuilder。构建选择器的。如:扫描什么包的注解.apis(RequestHandlerSelectors.basePackage(com.wxy.springboot_swagger.controller)); //规则,设定扫描哪个包包含子包3、自定义注解设置不需要生成接口文档的方法 ▶Target-描述当前的注解可以定义在什么资源上 属性value定义具体的资源常用 ElementType.METHOD可以定义在方法上EIementType.TYPE可以定义在类型上ElementType.FIELD可以定义在属性上ElementType.PARAMETER可以定义在方法参数上…… ▶Retention-当前注解在什么时候有效 属性value-定义具体的生效标记三个 RetentionPolicy.RUNTIME-运行时有效(常用)RetentionPolicy.SOURCE一源码中有效RetentionPolicy.CLASS-字节码有效 ▶示例 1.写一个自定义注解类 /** interface 代表当前是一个注解类/ Target(value {ElementType.METHOD,ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) public interface MyAnnotationSwagger {//自定义注解中的属性。相当于MyAnnotationSwagger(value)String value() default ; }2.自定义注解的使用实现controller中“req()”方法不在文档视图中显示 要在controller中req()的方法上添加注解MyAnnotationSwagger 在配置类中设置规则匹配器内部是静态方法 docket docket.select() //获取Docket中的选择器。返回ApiSelectorBuilder。构建选择器的。如:扫描什么包的注解//.apis(RequestHandlerSelectors.basePackage(com.wxy.springboot_swagger2.controller)) //规则,设定扫描哪个包包含子包.apis(Predicates.not( //取反false-true true-falseRequestHandlerSelectors.withMethodAnnotation( //withMethodAnnotation:当方法上有注解时返回trueMyAnnotationSwagger.class)) //方法有什么注解的时候返回true).build(); //重新构建Docket对象测试只有get和post两个方法了 Predicates.and()
4、配置路径范围配置paths() .paths(PathSelectors.regex(/swagger/.) //使用正则表达式约束生成API文档的路径地址。//控制器访问路径以swagger开头的。RequestMapping(/swagger) ).paths(Predicates.or( //多个规则符合任意一个即可通过。PathSelectors.regex(pathRegex:/swagger/.),PathSelectors.regex(pathRegex:/swagger2/.),PathSelectors.regex(pathRegex:/.)) )六、Swagger2常用注解 常用注解 swagger通过注解表明该接口会生成文档包括接口名、请求方法、参数、返回信息的等等。 Api修饰整个类描述Controller的作用。 tags给当前类型定义别名可以有多个。定义几个别名在ui视图中就显示几个控制器访问菜单。description定义描述 ApiOperation描述一个类的一个方法或者说一个接口ApiParam单个参数描述ApiModel描述实体类型用对象来接收参数ApiModelProperty用对象接收参数时描述对象的一个字段ApiImplicitParam在方法上描述方法的一个请求参数ApiImplicitParams多个请求参数ApiIgnore忽略当前注解描述的方法或类型不生成api帮助文档 Api RestController RequestMapping(/user) Api(tags {MyController,Swagger测试控制器},description 测试API类型描述信息) public class MyController {…… }ApiOperation PostMapping(/getUserById)//post请求ApiOperation(value post方法执行新增操作, notes Swagger学习使用-处理POST请求的方法)public String post(Integer id){return post:根据id获取User;}ApiParam ApiImplicitParam-s GetMapping(/test) ApiImplicitParam(name m, value m参数描述,required false, paramType 字符串,dataType 明值对) public String test(String m,String n){return request; }ApiImplicitParams(value {ApiImplicitParam(name m, value m参数描述,required false, paramType 字符串,dataType 明值对),ApiImplicitParam(name n, value n参数描述,required true, paramType 字符串,dataType 明值对)})ApiModel、ApiModelProperty /** ApiModel 描述一个实体类型。这个实体类型如果成为任何一个生成api帮助文档方法的* 返回值类型的时候此注解被解析。*/ ApiModel(value 自定义实体类,description MyEntity存储用户数据) public class MyEntity implements Serializable {ApiModelProperty(value 主键,name 主键(id),required false,example 1,hidden false)private String id;ApiModelProperty(value 姓名,name 姓名(name),required true,example 张三,hidden false)private String name;ApiModelProperty(value 密码,name 密码(password),required true,example 123456,hidden false)private String password;public MyEntity(){}public String getId() {return id;}public void setId(String id) {this.id id;}public String getName() {return name;}public void setName(String name) {this.name name;}public String getPassword() {return password;}public void setPassword(String password) {this.password password;}Overridepublic boolean equals(Object o) {if (this o) return true;if (o null || getClass() ! o.getClass()) return false;MyEntity myEntity (MyEntity) o;return Objects.equals(id, myEntity.id) Objects.equals(name, myEntity.name) Objects.equals(password, myEntity.password);}Overridepublic int hashCode() {return Objects.hash(id, name, password);} }返回类型是实体类类型 RequestMapping(/testEntity)public MyEntity testEntity(){return new MyEntity();}