swagger2接口文档

简介

前后端使用的接口文档，如前端访问后端哪个接口、得到的哪个参数等等

前台人员写登录页面 /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)

---

---

基础信息配置

使用配置类+注解来配置一个基础信息的配置

创建一个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", // 文档发布者的网站地址   企业地址
                                "[email protected]") // 文档发布者的电子邮箱
                )
                .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;
    }


}