swagger2接口文档
| 阿里云国内75折 回扣 微信号：monov8 |
| 阿里云国际，腾讯云国际，低至75折。AWS 93折 免费开户实名账号 代冲值 优惠多多 微信号：monov8 飞机：@monov6 |
文章目录
简介
前后端使用的接口文档如前端访问后端哪个接口、得到的哪个参数等等
前台人员写登录页面 /login 有两个参数 username pswd
后台人员写登录页面/dologin 参数名称 username password
前台后台要不断的更新自己的内容去配合这就很麻烦因为每个人的开发习惯不一样
接口文档请求地址 端口 参数有几个 都是什么类型 返回结果有哪些…,但是文档更新不及时
swagger能够根据代码动态的生成接口
Open API
是一种规范以前叫做Swagger规范是REST API的API描述格式
Open API 文件描述整个API包括
1、每个访问地址的类型 POST和GET…
2、每个操作的参数 输入输出参数
3、认证方法 有没有加密
4、连接信息、声明、使用团队和其他信息
Open API 规范可以使用
YAML或者JSON格式进行编写这样更有利于我们和机器进行阅读OpenAPI规范OAS为REST API定义了一个
与语言无关的标准接口
Swagger简介
是一套围绕Open API规范构建的开源工具可以帮助设计、构建、记录和使用REST API 专门做Open API具体实现的
Swagger工具包括的组件
Swagger Editor 相对用的少 偶然在配置中出现文档的定制化编写基于浏览器编辑器类似Markdown程序员还得手写
Swagger UI将代码中嵌入的Swagger内容注解读出将Open API规范呈现为交互式API文档用可视化UI展示描述文件用浏览器查看 Swagger Codegen将OpenAPI规范生成为服务器存根和客户端库客户端库一般就是html格式或者cwiki形式而服务器存根一般是各种代码
Swagger Inspector类似于UI 但是加了过程记录用的少
Swagger Hub集成上面所有的功能可以以项目和版本为单位将描述文件上传到Swagger Hub中在Swagger Hub中可以完成上面项目的所有工作类似GitHub
使用Swagger
将描述信息写成yml或者json格式然后通过UI观看,根据代码的变化改变yml或者json中的内容去更新文档
Spring-fox
是Swagger的一种加强
使用Swagger时如果碰见版本更新或者迭代时需要修改Swagger的描述文件也就是yml或者json格式但是这也是一种工作负担所以出现了Springfox来自动修改通过注解来写一个描述文件最后生成一个接口文档。 ‘
Spring-fox是在spring的组件
swagger-springmvc中发展而来的组件,但是它不是spring旗下的可以根据代码生成主要使用AOP技术将swagger集成进来底层还是Swagger实际开发中都是使用
spring-fox+swagger来配合使用
入门案例
第一步导入依赖
<!--管理springboot-->
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>2.3.12.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<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>
</dependencies>
第二步编写controller类
@RestController
public class DemoController {
@PostMapping("/post")
public String post(){
return "post";
}
@GetMapping("/get")
public String get(String a,String b){
return "get";
}
@RequestMapping("/login")
public String login(String name){
return "name";
}
}
第三步编写启动类
@EnableSwagger2 是springfox提供的一个注解代表swagger2相关技术开启会扫描当前类所在包及子包中所有的类型中的注解做swagger文档的定值
@SpringBootApplication
@EnableSwagger2
public class MyApp {
public static void main(String[] args) {
SpringApplication.run(MyApp.class,args);
}
}
第四步运行启动类并访问ui页面
localhost:8080/swagger-ui.html
Swagger UI 介绍
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-br8kFhIZ-1675481160322)![(.\swagger2.assets\1672112512021.png)]](https://img-blog.csdnimg.cn/5650e1f068c34e9a8baf65d65b4e1de4.png)
基础信息配置
使用配置类+注解来配置一个基础信息的配置
创建一个Docket类型的对象并使用spring容器管理Docket是Swagger中的全局配置对象
设置文档名称、网站地址、邮箱、标题、描述、版本、扫描包所在位置。
apis是一套规则不止是下面的规则还有很多。
@Configuration
public class swaggerAPIInfo {
@Bean
public Docket docket(){
// 创建Swagger全局对象并指定使用哪个版本的
Docket docket = new Docket(DocumentationType.SWAGGER_2);
// 创建API帮助文档的描述信息
ApiInfo apiInfo = new ApiInfoBuilder()
// 配置Swagger文档主体内容
.contact(
new Contact("南方有橘 - wanwan", // 文档的发布者名称
"http://localhost:8080", // 文档发布者的网站地址 企业地址
"2523318777@qq.com") // 文档发布者的电子邮箱
)
.title("Swagger框架学习帮助文档")
.description("Swagger框架学习帮助文档详细描述-Swagger框架是一个用于开发RestAPI帮助文档的框架")
.version("1.1")
.build();
// 给docket上下文配置api描述信息
docket.apiInfo(apiInfo);
// 配置Swagger扫描包
docket = docket
.select() // 获得Docket中的选择器返回APISelectorBuilder 如扫描什么包下的注解
.apis( // 返回true然后取反为false最后就不会展示在文档上
Predicates.and(
Predicates.not( // 取反 将false=>true
// 当方法上有该MyAnnotation4Swagger注解的时候返回true
RequestHandlerSelectors.withMethodAnnotation(MyAnnotation4Swagger.class)
),
RequestHandlerSelectors.basePackage("com.ww.swaggerDemo.Controller") // 设定扫描哪个包中的注解
)
)
.build(); // 重新构建
return docket;
}
}
自定义注解防止有些类不生成接口文档
@Target 描述当前的注解可以定义在什么资源上。
属性 value
- 定义具体的资源 包括
ElementType.METHOD可以定义在方法上ElementType.TYPE可以定义在类型上ElementType.FIELD可以定义在属性上ElementType.PARAMETER可以定义在方法参数上
@Retention 当前注解在什么时候有效
属性 value
- 定义具体的生效标记
RetentionPolicy.RUNTIME运行时有效RetentionPolicy.SOURCE源码中有效RetentionPolicy.CLASS字节码中有效
@Target({ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation4Swagger {
//自定义注解中的属性
String value() default "";
}
配置-不想被写入接口文档中的方法
当在生成接口文档的时候有些方法不想被写入接口文档中这个时候就需要在配置类中进行规则的配置
配置-controller前缀为xx的才被写入接口文档
controller方法中只有以/swagger或者/swagger1 开头的才能生成接口文档
常用注解
类 - @Api(tags = {"别名1" , "别名2"}) 生成帮助文档的信息,定义多个别名则出现多个名字不同但是所拥有的方法相同的文档
方法 - @ApiOperation(value="方法标题",notes="方法描述")
方法参数 - @ApiParam(name="参数名称",value="参数描述",required=是否必须......) String a
忽略生成接口文档 @ApiIgnore
跟之前自己在配置类中进行的配置一样所以之前的那个配置类中的配置可以不用转而用这个注解
方法参数 - @ApiImplicitParams(
value={ @ApiImplicitParam(name="参数名"value=“参数描述”required=是否必要paramType=“参数类型如字符串”dataType=“数据类型”) , @ApiImplicitParam()})
也可以单独写 @ApiImplicitParam
ApiModel和ApiModelProperty
用在方法返回值为实体类的情况
@ApiModel(value = "实体类Entiy",description = "这个实体类用来收集用户的信息")
public class entiy implements Serializable {
@ApiModelProperty(name = "主键",value = "主键id",required = false,example = "1")
private String id;
@ApiModelProperty(name = "用户名",value = "用户名name",required = true,example = "张三")
private String name;
@ApiModelProperty(name = "密码",value = "密码pwd",required = true,example = "admin")
private String pwd;
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 getPwd() {
return pwd;
}
public void setPwd(String pwd) {
this.pwd = pwd;
}
}
