文章目录
- 简介
- Open API
- Swagger简介
- Spring-fox
- 入门案例
- 第一步：导入依赖
- 第二步：编写controller类
- 第三步：编写启动类
- 第四步：运行启动类并访问ui页面
- Swagger UI 介绍
- 基础信息配置
- 自定义注解（防止有些类不生成接口文档）
- 配置-不想被写入接口文档中的方法
- 配置-controller前缀为xx的才被写入接口文档
- 常用注解
- ApiModel和ApiModelProperty
简介
前后端使用的接口文档，如前端访问后端哪个接口、得到的哪个参数等等
前台人员写登录页面 /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;
}
}
![[NeurIPS 2017] Poincaré Embeddings for Learning Hierarchical Representations](https://img-blog.csdnimg.cn/c983d9214c8a43119bebe6dd8c99b640.png#pic_center)
