网站建设佛山,网址短链接在线生成免费,免费制作宣传册的app,哪个网站做淘宝客最合适Swagger3 API接口文档规范课程#xff08;内含教学视频源代码#xff09;
教学视频源代码下载链接地址#xff1a;https://download.csdn.net/download/weixin_46411355/87431932 目录Swagger3 API接口文档规范课程#xff08;内含教学视频源代码#xff09;教学视频源代…Swagger3 API接口文档规范课程内含教学视频源代码
教学视频源代码下载链接地址https://download.csdn.net/download/weixin_46411355/87431932 目录Swagger3 API接口文档规范课程内含教学视频源代码教学视频源代码下载链接地址[https://download.csdn.net/download/weixin_46411355/87431932](https://download.csdn.net/download/weixin_46411355/87431932)1.Swagger3 简介2.Swagger3 HelloWorld实现第一步我们新建一个SpringBoot项目第二步开启Swagger第三步新建HelloWorldController.java控制器类第四步访问swagger-ui查看接口文档第五步Swagger注解描述接口3 Swagger3 常用配置注解讲解3.1 Swagger3常用配置如下3.2 实例一 ApiImplicitParams 和 ApiImplicitParam 参数描述3.3 实例二 ApiModel , ApiModelProperty 实体参数描述3.4 实例三 ApiResponses ApiResponse4 Swagger3 接口测试5 Swagger3 API信息配置6 Swagger3 Docket 开关过滤分组 配置详解6.1 开关设置enable6.2 设置过滤6.3 设置分组1.Swagger3 简介
Swagger丝袜哥是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统数以千计的开发人员使用几乎所有的现代编程语言都在支持和使用Swagger。使用Swagger生成API我们可以得到交互式文档自动生成代码的SDK以及API的发现特性等。
前后端分离的项目接口文档的存在十分重要。与手动编写接口文档不同swagger是一个自动生成接口文档的工具在需求不断变更的环境下手动编写文档的效率实在太低。与swagger2相比新版的swagger3配置更少使用更加方便。
官网 https://swagger.io/
在线编辑器 http://editor.swagger.io/
Swagger作用
将项目中所有的接口展现在页面上这样后端程序员就不需要专门为前端使用者编写专门的接口文
档
当接口更新之后只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了从而规避了接口文档老旧不能使用的问题通过 Swagger 页面我们可以直接进行接口调用降低了项目开发阶段的调试成本。
现在SWAGGER官网主要提供了几种开源工具提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果
Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包dockernode等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector: 感觉和postman差不多是一个可以对接口进行测试的在线版的postman。比在 Swagger UI里面做接口请求会返回更多的信息也会保存你请求的实际请求参数等数据。
Swagger Hub集成了上面所有项目的各个功能你可以以项目和版本为单位将你的描述文件上传到 Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作需要注册账号分免费版和收费版。
2.Swagger3 HelloWorld实现
第一步我们新建一个SpringBoot项目 加一个Spring Web依赖
加下Swagger依赖
dependencygroupIdio.springfox/groupIdartifactIdspringfox-boot-starter/artifactIdversion3.0.0/version/dependency这里用的是 springfoxSwagger 可以看作是一个遵循了 OpenAPI 规范的一项技术而 springfox 则是这项技术的具体实现。
类似 JDBC是一套技术规范各大数据库都有JDBC的实现
最终项目pom.xml
?xml version1.0 encodingUTF-8?
project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsdmodelVersion4.0.0/modelVersionparentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion2.7.8/versionrelativePath/ !-- lookup parent from repository --/parentgroupIdcom.java1234/groupIdartifactIdswagger-demo/artifactIdversion0.0.1-SNAPSHOT/versionnameswagger-demo/namedescriptionDemo project for Spring Boot/descriptionpropertiesjava.version1.8/java.version/propertiesdependenciesdependencygroupIdio.springfox/groupIdartifactIdspringfox-boot-starter/artifactIdversion3.0.0/version/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependenciesbuildpluginsplugingroupIdorg.springframework.boot/groupIdartifactIdspring-boot-maven-plugin/artifactId/plugin/plugins/build/project
第二步开启Swagger
在Spring Boot 的启动类添加 EnableOpenApi 注解开启 Swagger支持
package com.java1234.swaggerdemo;import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;EnableOpenApi
SpringBootApplication
public class SwaggerDemoApplication {public static void main(String[] args) {SpringApplication.run(SwaggerDemoApplication.class, args);}}
第三步新建HelloWorldController.java控制器类
package com.java1234.swaggerdemo.controller;import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;RestController
public class HelloWorldController {RequestMapping(/helloWorld)public String helloWorld() {return helloWorld;}
}
运行启动类 如果报错 报错信息如下
Failed to start bean ‘documentationPluginsBootstrapper‘ nested exception is java.lang.NullPoint可以查看笔者的另一篇博文《解决报错Failed to start bean ‘documentationPluginsBootstrapper‘ nested exception is java.lang.NullPoint》————https://huanghaoheng.blog.csdn.net/article/details/128884811 再次运行启动类 浏览器访问http://localhost:8080/helloWorld 没问题
第四步访问swagger-ui查看接口文档
浏览器访问http://localhost:8080/swagger-ui/
显示如下图主要三大区域分组定义信息区块API文档上信息区块以及最重要的接口定义信息区块 展开HelloWorldController接口定义 这里我们能看到枚举了所有可能的请求类型因为我们用了 RequestMapping 以及请求地址 /helloWorld 我们再点开任意一个请求 我们可以看到接口没有参数返回值是 String 类型
这里描述了完整的接口定义信息前端开发人员一目了然假如接口定义变化前端开发人员刷新下swagger-ui就能及时看到比起以往的人工编写接口文档方便很多
第五步Swagger注解描述接口
在接口描述的时候控制器类以及方法参数返回值等默认的话是英文无备注信息可能会让前端开发人员看起来吃力会增加沟通成本
Swagger提供一套注解我们给接口添加中文注释
我们在类上添加 API 注解以及在方法上添加 ApiOperation 注解 package com.java1234.swaggerdemo.controller;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;Api(tags helloworld测试类)
RestController
public class HelloController {ApiOperation(测试方法)RequestMapping(/helloWorld)public String helloWorld() {return helloWorld;}
} 重启项目刷新swagger-ui发现已经以后中文注释了
3 Swagger3 常用配置注解讲解
3.1 Swagger3常用配置如下
swagger提供了一些配置用来描述接口下面是一些常用的注解必须掌握
3.2 实例一 ApiImplicitParams 和 ApiImplicitParam 参数描述
post方式根据name和age两个参数查询数据返回信息
我们用 ApiImplicitParams 和 ApiImplicitParam 描述请求参数 /***param name*param age*return*/ApiOperation(测试查询)ApiImplicitParams({ApiImplicitParam(name name,value 姓名,required true,paramType query),ApiImplicitParam(name age,value 年龄,required true,paramType query,dataType Integer)})PostMapping(/search)public String search(String name, Integer age){return name:age;}swagger控制台显示 点击Try it out
3.3 实例二 ApiModel , ApiModelProperty 实体参数描述
我们搞一个用户信息添加,使用 ApiModel , ApiModelProperty 注解来描述输入参数
先搞一个用户信息实体User.java
package com.java1234.swaggerdemo.entity;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.models.auth.In;ApiModel(用户实体类)
public class User {ApiModelProperty(编号)private Integer id;ApiModelProperty(姓名)private String name;ApiModelProperty(年龄)private Integer age;public User() {}public User(Integer id, String name, Integer age) {this.id id;this.name name;this.age age;}public Integer getId() {return id;}public void setId(Integer id) {this.id id;}public String getName() {return name;}public void setName(String name) {this.name name;}public Integer getAge() {return age;}public void setAge(Integer age) {this.age age;}Overridepublic String toString() {return User{ id id , name name \ , age age };}
}
参数上直接用 User user /*** 添加测试* param user* return*/ApiOperation(测试添加)PostMapping(/add)public String add(User user){return user.getName():user.getAge(); }swagger控制台显示 点击Try it out
3.4 实例三 ApiResponses ApiResponse
我们搞一个根据id获取用户信息案例通过 PathVariable 获取id返回User对象以及通过 ApiResponses ApiResponse 描述响应码对应的描述信息 /*** ApiImplicitParam* paramType : 参数放在哪个地方* path(用于restful接口) : 请求参数的获取PathVariable* param id* return*/ApiOperation(根据ID获取用户信息)ApiImplicitParams({ApiImplicitParam(nameid,value 用户编号,required true,paramType path)})ApiResponses({ApiResponse(code 408,message 指定业务的报错信息返回客户端),ApiResponse(code 400,message 请求参数没填好),ApiResponse(code 404,message 请求路径没有或页面跳转路径不对)})GetMapping(/user/{id})public User load(PathVariable(id) Integer id){return new User(id,jack,32);}swagger控制台显示 点击Try it out Schemas也对应有视图用户实体描述信息显示
4 Swagger3 接口测试
swagger-ui图形客户端提供了接口测试功能
5 Swagger3 API信息配置 默认情况显示的API信息如下 默认情况下这些参数都不能填写禁用的 我们点击“Try it out”按钮即可开启接口测试功能 输入请求参数后点击“Execute‘按钮即可执行下方是后端返回信息
类似的我们可以测试添加功能 说明很多时候前后端分离传的是json键值对用swagger-ui提供的简陋接口测试工具很难用所以接口测试我们还是用专业的 postman
5 Swagger3 API信息配置
默认情况显示的API信息如下 通过源码我们可以看到这个信息是通过springfox.documentation.service.ApiInfo.java 类来构造的 最终通过 springfox.documentation.spring.web.plugins.Docket.java 类的构造方法传入 ApiInfo 类来最终构造 我们要修改API信息默认配置的话可以通过新建一个 com.java1234.config.Swagger3Config.java 配置类重写 ApiInfo 实现以及重写 Docket 实现并且设置apiInfo
源码 package com.java1234.swaggerdemo.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;import java.util.ArrayList;Configuration
public class Swagger3Config {/*** 配置swagger的Docket bean* return*/Beanpublic Docket createRestApi(){return new Docket(DocumentationType.OAS_30)//指定swagger3.0版本.apiInfo(creareApiInfo());}/*** 配置swagger的ApiInfo bean* return*/private ApiInfo creareApiInfo() {return new ApiInfo(Java1234 Swagger,Java1234 Api Documentation,3.0,http://www.java1234.vip,new Contact(小锋,http://www.java1234.vip,caofeng2012126.com),Apache 2.0,http://www.apache.org/licenses/LICENSE-2.0,new ArrayList());}}
重启项目我们发现APIInfo信息变了 这个API信息主要作用是让前端开发人员看的谁开发的接口或者哪个小组负责有问题方便联系沟通
6 Swagger3 Docket 开关过滤分组 配置详解
我们可以通过设置Docket可以配置很多功能比如是否开启swagger过滤分组等
6.1 开关设置enable
一般情况我们只有在开发环境才会用到swagger正式环境需要关闭swagger一个是安全问题还有一个是用了swagger会影响系统运行速度
我们通过设置Docket对象的enable即可
/*** 配置swagger的Docket bean** return*/Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30)//指定swagger3.0版本.apiInfo(creareApiInfo()).enable(false);}设置后重启项目发现已经看不到API信息了
6.2 设置过滤
有些情况我们需要指定固定包路径下的类生成API或者根据前端用户路径请求过滤 使用过滤必须先调用 select 方法 通过apis方法 basePackage 可以根据包路径来生成特定类的API any 方法是默认所有都有效 none 方法都无效 withClassAnnotation 根据类注解 withMethodAnnotation 是根据方法注解一般我们用的是 basePackage 方法 具体实例 /*** 配置swagger的Docket bean** return*/Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30)//指定swagger3.0版本.select().apis(RequestHandlerSelectors.basePackage(com.java1234.swaggerdemo.controller))//指定扫描的包 常用方式.build().apiInfo(creareApiInfo()).enable(true);//开关}最后要加 build() 方法
类似的还有一个根据请求路径的 paths 方法 一般用 ant 匹配路径 any 是匹配任意路径 none 是都不匹配 regex 是正则匹配 具体实例 /*** 配置swagger的Docket bean** return*/Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30)//指定swagger3.0版本.select().apis(RequestHandlerSelectors.basePackage(com.java1234.swaggerdemo.controller))//指定扫描的包 常用方式.paths(PathSelectors.ant(/java1234/**))//匹配 /java1234/**请求路径.build().apiInfo(creareApiInfo()).enable(true);//开关}在controller层家一个方法 GetMapping(/java1234/testPathMethod)public String testPathMethod(){return testPathMethod;}重启访问 swagger-ui视图只显示过滤后的API接口信息
6.3 设置分组
在实际项目开发中把复杂项目划分多模块给多个小组或者多个人负责开发所以每个小组或者个人要实现自己的分组方便查找到API接口开发负责人沟通和处理问题
我们通过 groupName 方法可以设置组名 实例 /*** 配置swagger的Docket bean** return*/Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30)//指定swagger3.0版本.groupName(开发组001).select().apis(RequestHandlerSelectors.basePackage(com.java1234.swaggerdemo.controller))//指定扫描的包 常用方式.paths(PathSelectors.ant(/java1234/**))//匹配 /java1234/**请求路径.build().apiInfo(creareApiInfo()).enable(true);//开关}刷新界面 发现组名变了
现在的话我们结合前面学过的过滤通过apis的basePackage方法搞两个组分别扫描不同的包路径
模拟分组开发controller包下建两个子包分别是one和two包用来模拟两个业务模块将HelloWorldController移入到one包下
简单搞个 HelloWorldController2
package com.java1234.swaggerdemo.controller.two;import com.java1234.swaggerdemo.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;Api(tags helloworld测试类2)
RequestMapping(/java1234/)
RestController
public class HelloWorldController2 {ApiOperation(测试方法2)GetMapping(/helloWorld2)public String helloWorld2(){return helloWorld2;}}
我们搞两个 Docket 和两个 ApiInfo
package com.java1234.swaggerdemo.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;import java.util.ArrayList;Configuration
public class Swagger3Config {/*** 配置swagger的Docket bean** return*/Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30)//指定swagger3.0版本.groupName(开发组001).select().apis(RequestHandlerSelectors.basePackage(com.java1234.swaggerdemo.controller.one))//指定扫描的包 常用方式.paths(PathSelectors.ant(/java1234/**))//匹配 /java1234/**请求路径.build().apiInfo(creareApiInfo()).enable(true);//开关}/*** 配置swagger的ApiInfo bean** return*/private ApiInfo creareApiInfo() {return new ApiInfo(Java1234 Swagger,Java1234 Api Documentation,3.0,http://www.java1234.vip,new Contact(小锋, http://www.java1234.vip, caofeng2012126.com),Apache 2.0,http://www.apache.org/licenses/LICENSE-2.0,new ArrayList());}/*** 配置swagger的Docket bean** return*/Beanpublic Docket createRestApi2() {return new Docket(DocumentationType.OAS_30)//指定swagger3.0版本.groupName(开发组002).select().apis(RequestHandlerSelectors.basePackage(com.java1234.swaggerdemo.controller.two))//指定扫描的包 常用方式.paths(PathSelectors.ant(/java1234/**))//匹配 /java1234/**请求路径.build().apiInfo(creareApiInfo2()).enable(true);//开关}/*** 配置swagger的ApiInfo bean** return*/private ApiInfo creareApiInfo2() {return new ApiInfo(Java1234 Swagger,Java1234 Api Documentation,3.0,http://www.java1234.vip,new Contact(小丽, http://www.java1234.vip, caofeng2012126.com),Apache 2.0,http://www.apache.org/licenses/LICENSE-2.0,new ArrayList());}}
启动项目运行
开发组001 开发组002 测试OK;
