Swagger

最新推荐文章于 2024-07-19 11:14:01 发布

潇洒（sa）一点

最新推荐文章于 2024-07-19 11:14:01 发布

阅读量566

点赞数

文章标签： restful 前端 java

本文链接：https://blog.csdn.net/qq_60281421/article/details/130641441

版权

Swagger简介

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。很多人员会抱怨别人写的接口文档不规范，不及时更新。如果接口文档可以实时动态生成就不会出现上面问题，Swagger可以完美地解决上面的问题。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful 【/10/20/admin】风格的 Web 服务，可用于接口的文档在线自动生成以及功能测试。

Open API 是什么 Open API 规范(OpenAPI Specification)以前叫做 Swagger 规范，是REST API【json】的 API 描述格式。Open API 文件允许描述整个 API，包括：

每个访问地址的类型。POST 或 GET

每个操作的参数。包括输入输出参数

认证方法

连接信息，声明，使用团队和其他信息。

Open API 规范可以使用YAML或 JSON格式进行编写，这样更利于我们和机器进行阅读。

Swagger和Open API

Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用 REST API。Swagger工具包括的组件：

1.Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown具有实时预览描述文件的功能。

2.Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI展示描述文件。

3.Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。

4.Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。

5.Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 SwaggerHub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码

通过Springfox使用Swagger:

使用 Swagger 时如果碰见版本更新，只需要更改Swagger的描述文件即可。但是在频繁地更新项目版本时很多开发人员认为即使修改描述文件（yml 或 json）也有一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也就失去了意义。

由于Spring的流行，Marty Pitt 编写了一个基于Spring 的组件 swagger-springmvc。Spring-fox 就是根据这个组件发展而来的全新项目。Spring-fox 是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。Springfox 利用自身 AOP 特性，把 Swagger 集成进来，底层还是Swagger。但是使用起来确方便很多。所以在实际开发中，都是直接使用 spring-fox。

官网地址：GitHub - springfox/springfox: Automated JSON API documentation for API's built with Spring

创建springboot项目:

项目中 controller 中包含一个 Handler，用于测试项目，保证程序可以正确运行。

创建boot项目swggertest

修改pom.xml：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.6.13</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.ss.demo</groupId>
    <artifactId>swggertest</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swggertest</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <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>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

创建包entity，并创建类Users

package com.ss.demo.entity;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Users {
    private int id;
    private String name;
    private int age;
    private String sex;
    private String addr;
}

创建包controller，并创建类IndexController

package com.ss.demo.controller;
import com.ss.demo.entity.Users;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/users")
public class IndexController {
    @RequestMapping("/getUser")
    public Users getUser(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(18);
        users.setSex("男");
        users.setAddr("北京");
        return users;
    }
}

在 SpringBoot 的启动类中添加@EnableSwagger2 注解。添加此注解后表示对当前项目中全部控制器进行扫描，应用Swagger2。

package com.ss.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2  //开启Swagger
public class SwggertestApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwggertestApplication.class, args);
    }
}

Application.yml:

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

然后启动该项目

启动项目后在浏览器中输入http://ip:port/swagger-ui.html即可以访问到 swagger-ui 页面，在页面中可以可视化的进行操作项目中所有接口。\

浏览器输入：http://localhost:8080/swagger-ui.html#/

我们index-controller后我们发现我们这里所有的请求类型全部出来了

这个时候我们如果把IndexController中的请求类型进行换成post的我们来进行查看下

package com.ss.demo.controller;

import com.ss.demo.entity.Users;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/users")
public class IndexController {
    @PostMapping("/getUser")
    public Users getUser(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(18);
        users.setSex("男");
        users.setAddr("北京");
        return users;
    }
}

重启项目我们再来进行查看

我们会发现只有一个post的请求类型

至此我们的最简单的接口文档已经生成了

SwaggerUI的使用和配置

访问 swagger-ui.html 可以在页面中看到所有需要生成接口文档的控制器名称

每个控制器包含该控制器下所有的方法及访问方式。如果使用的是 @RequestMapping 进行映射，将显示下面的所有请求方式。如果使用@PostMapping 将只有 Post 方式可以能访问，下面也就只显示Post 的一个。

当前我们也可以在控制器中添加一个方法进行查看

package com.ss.demo.controller;

import com.ss.demo.entity.Users;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users")
public class IndexController {

    @PostMapping("/getUser")
    public Users getUser(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(18);
        users.setSex("男");
        users.setAddr("北京");
        return users;
    }

    @GetMapping("/getUser1")
    public Users getUser1(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(20);
        users.setSex("女");
        users.setAddr("上海");
        return users;
    }
}

查看swgger：

点击某个请求方式中 try it out进行测试操作，我们来请求某个接口

输入参数值，完成后点击 Execute 按钮进行测试，测试结果如下所示：

Swagger的配置

可以在项目中创建包config，并创建配置类 SwaggerConfig，进行配置文档内容

配置基本信息

启动服务器进行测试，我们再次进入swgger-ui界面进行查看

设置扫描的包

可以通过 apis()方法设置哪个包中内容被扫描，如果设定的包被扫描到就会生成API文档

我们修改配置类SwaggerConfig下的 方法getDocket

package com.ss.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
* swgger2的配置类
*/
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket getDocket(){
        return new
                Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ss.demo.controller"))
                .build();
    }

    //对swgger-ui界面的配置操作
    private ApiInfo swaggerDemoApiInfo(){
        return new ApiInfoBuilder()
                .contact(new Contact("北大青鸟", "http://www.bdqn.cn","123@qq.com"))
                //文档标题
                .title("这里是Swagger的标题")
                //文档描述
                .description("这里是Swagger的描述")
                //文档版本
                .version("1.0.0")
                .build();
    }
}

下面我们在controller中创建另一个测试控制器TestController，用它来进行测试：

我们看到在controller包下的控制器都生成了API文档

自定义注解设置不需要生成接口文档的方法【就是在上面的被扫描的包中，哪些控制器的类不需要生成API文档】

注解名称自定义

在项目的包config下创建自定义注解：

package com.ss.demo.config;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.METHOD}) //该注解含义是我的这个注解针对的是方法
@Retention(RetentionPolicy.RUNTIME) //表示在运行时会去调用这个注解
public @interface NotIncludeSwagger {
}

我们修改配置类SwaggerConfig下的 方法getDocket

package com.ss.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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 static com.google.common.base.Predicates.not;
import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

/**
* swgger2的配置类
*/
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket getDocket(){
        return new
                Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ss.demo.controller"))
                .apis(not((withMethodAnnotation(NotIncludeSwagger.class))))
                .build();
    }

    //对swgger-ui界面的配置操作
    private ApiInfo swaggerDemoApiInfo(){
        return new ApiInfoBuilder()
                .contact(new Contact("北大青鸟", "http://www.bdqn.cn","123@qq.com"))
                //文档标题
                .title("这里是Swagger的标题")
                //文档描述
                .description("这里是Swagger的描述")
                //文档版本
                .version("1.0.0")
                .build();
    }
}

我们测试下@ NotIncludeSwagger这个注解如果标注在某个类上的某个方法上看看是否不生成API 文档

启动测试下

设置范围

通过下面的代码：

可以设置满足什么样规则的 url 被生成接口文档。可以使用正则表达式进行匹配。

下面例子中表示只有以/demo/开头的 url 才能被 swagger 生成接口文档。

我们还是在配置类SwaggerConfig下的方法getDocket进行操作

package com.ss.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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 static com.google.common.base.Predicates.not;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

/**
* swgger2的配置类
*/
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket getDocket(){
        return new
                Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ss.demo.controller"))
                //.apis(not((withMethodAnnotation(NotIncludeSwagger.class))))
                .paths(or(PathSelectors.regex("/users/.*"))) //正则表达式,单路径
                .build();
    }

    //对swgger-ui界面的配置操作
    private ApiInfo swaggerDemoApiInfo(){
        return new ApiInfoBuilder()
                .contact(new Contact("北大青鸟", "http://www.bdqn.cn","123@qq.com"))
                //文档标题
                .title("这里是Swagger的标题")
                //文档描述
                .description("这里是Swagger的描述")
                //文档版本
                .version("1.0.0")
                .build();
    }
}

匹配多路径：

  @Bean
    public Docket getDocket(){
        return new
                Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ss.demo.controller"))
                //.apis(not((withMethodAnnotation(NotIncludeSwagger.class))))
                .paths(or(PathSelectors.regex("/users/.*"),PathSelectors.regex("/test/.*"))) //正则表达式,多路径
                .build();
    }

如果希望全部扫描，全部生成接口文档，我们可以按照以下写法进行操作【这个也是默认】

paths(PathSelectors.any())

======================================================

Swagger2 常用注解

Api注解：

在项目swggertest的controller的IndexController进行测试：

package com.ss.demo.controller;

import com.ss.demo.entity.Users;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users")
@Api(tags = "myDemo", description="描述信息")
public class IndexController {

    @PostMapping("/getUser")
    public Users getUser(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(18);
        users.setSex("男");
        users.setAddr("北京");
        return users;
    }

    @GetMapping("/getUser1")
    public Users getUser1(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(20);
        users.setSex("女");
        users.setAddr("上海");
        return users;
    }
}

浏览器输入地址：http://localhost:8080/swagger-ui.html#/

ApiOperation

package com.ss.demo.controller;

import com.ss.demo.entity.Users;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users")
@Api(tags = "myDemo", description="描述信息")
public class IndexController {

    @PostMapping("/getUser")
    @ApiOperation(value = "获得用户信息", notes = "根据用户编号和用户名称获得用户信息")
    public Users getUser(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(18);
        users.setSex("男");
        users.setAddr("北京");
        return users;
    }

    @GetMapping("/getUser1")
    public Users getUser1(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(20);
        users.setSex("女");
        users.setAddr("上海");
        return users;
    }
}

测试：

ApiParam

package com.ss.demo.controller;

import com.ss.demo.entity.Users;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users")
@Api(tags = "myDemo", description="描述信息")
public class IndexController {

    @PostMapping("/getUser")
    @ApiOperation(value = "获得用户信息", notes = "根据用户编号和用户名称获得用户信息")
    public Users getUser(int id, @ApiParam(value = "姓名", required = true) String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(18);
        users.setSex("男");
        users.setAddr("北京");
        return users;
    }

    @GetMapping("/getUser1")
    public Users getUser1(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(20);
        users.setSex("女");
        users.setAddr("上海");
        return users;
    }
}

ApiModel

package com.ss.demo.entity;

import io.swagger.annotations.ApiModel;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户类",description = "描述信息")
public class Users {
    private int id;
    private String name;
    private int age;
    private String sex;
    private String addr;
}

ApiModelProperty

实体类属性上标注：

package com.ss.demo.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import javafx.scene.chart.ValueAxis;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户类",description = "描述信息")
public class Users {
    private int id;
    @ApiModelProperty(value = "姓名", name = "name", required = true, example = "李四")
    private String name;
    private int age;
    private String sex;
    private String addr;
}

ApiIgnore

package com.ss.demo.controller;

import com.ss.demo.entity.Users;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@RequestMapping("/users")
@Api(tags = "myDemo", description="描述信息")
public class IndexController {

    @PostMapping("/getUser")
    @ApiIgnore
    @ApiOperation(value = "获得用户信息", notes = "根据用户编号和用户名称获得用户信息")
    public Users getUser(int id, @ApiParam(value = "姓名", required = true) String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(18);
        users.setSex("男");
        users.setAddr("北京");
        return users;
    }

    @GetMapping("/getUser1")
    public Users getUser1(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(20);
        users.setSex("女");
        users.setAddr("上海");
        return users;
    }
}

ApiImplicitParam

package com.ss.demo.controller;

import com.ss.demo.entity.Users;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@RequestMapping("/users")
@Api(tags = "myDemo", description="描述信息")
public class IndexController {

    @PostMapping("/getUser")
    //@ApiIgnore
    @ApiOperation(value = "获得用户信息", notes = "根据用户编号和用户名称获得用户信息")
    public Users getUser(int id, @ApiParam(value = "姓名", required = true) String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(18);
        users.setSex("男");
        users.setAddr("北京");
        return users;
    }

    @ApiImplicitParam(name = "id", value = "编号", required = true, paramType = "query", dataType = "int")
    @GetMapping("/getUser1")
    public Users getUser1(int id, String name) {
        Users users = new Users();
        users.setId(id);
        users.setName(name);
        users.setAge(20);
        users.setSex("女");
        users.setAddr("上海");
        return users;
    }
}

多个参数的设置：

//@ApiImplicitParam(name = "id", value = "编号", required = true, paramType = "query", dataType = "int")
@ApiImplicitParams(value = {
        @ApiImplicitParam(name = "id", value = "编号", required = true, paramType = "query", dataType = "int"),
        @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query", dataType = "String"),
})
@GetMapping("/getUser1")
public Users getUser1(int id, String name) {
    Users users = new Users();
    users.setId(id);
    users.setName(name);
    users.setAge(20);
    users.setSex("女");
    users.setAddr("上海");
    return users;
}