SpringBoot Swagger2 接口规范示例详解

更新时间：2023年12月01日 16:25:38 作者：程序猿进阶

Swagger（在谷歌、IBM、微软等公司的支持下）做了一个公共的文档风格来填补上述问题,在本文中,我们将会学习怎么使用Swagger的 Swagger2注解去生成REST API文档,感兴趣的朋友一起看看吧

如今，REST和微服务已经有了很大的发展势头。但是，REST规范中并没有提供一种规范来编写我们的对外REST接口API文档。每个人都在用自己的方式记录api文档，因此没有一种标准规范能够让我们很容易的理解和使用该接口。我们需要一个共同的规范和统一的工具来解决文档的难易理解文档的混乱格式。Swagger（在谷歌、IBM、微软等公司的支持下）做了一个公共的文档风格来填补上述问题。在本博客中，我们将会学习怎么使用Swagger的 Swagger2注解去生成REST API文档。

Swagger(现在是“开放 API计划”)是一种规范和框架，它使用一种人人都能理解的通用语言来描述REST API。还有其他一些可用的框架，比如RAML、求和等等，但是 Swagger是最受欢迎的。它提供了人类可读和机器可读的文档格式。它提供了JSON和UI支持。JSON可以用作机器可读的格式，而 Swagger-UI是用于可视化的，通过浏览api文档，人们很容易理解它。

一、添加 Swagger2 的 maven依赖

打开项目中的 pom.xml文件，添加以下两个 swagger依赖。springfox-swagger2 、springfox-swagger-ui。

<dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.6.1</version>
</dependency>
<dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.6.1</version>
</dependency>

实际上，Swagger的 API有两种类型，并在不同的工件中维护。今天我们将使用 springfox，因为这个版本可以很好地适应任何基于 spring的配置。我们还可以很容易地尝试其他配置，这应该提供相同的功能——配置中没有任何变化。

二、添加 Swagger2配置

使用 Java config的方式添加配置。为了帮助你理解这个配置，我在代码中写了相关的注释：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import com.google.common.base.Predicates;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2UiConfiguration extends WebMvcConfigurerAdapter
{
    @Bean
    public Docket api() {
        // @formatter:off
        //将控制器注册到 swagger
        //还配置了Swagger 容器
        return new Docket(DocumentationType.SWAGGER_2).select()
                 .apiInfo(apiInfo())
                 .select()
                 .apis(RequestHandlerSelectors.any())
                 //扫描 controller所有包
                 .apis(Predicates.not(RequestHandlerSelectors.basePackage("org.springframework.boot")))
                 .paths(PathSelectors.any())
                 .paths(PathSelectors.ant("/swagger2-demo"))
                 .build();
        // @formatter:on
    }
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry)
    {
        //为可视化文档启用swagger ui部件
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

通过 api()方法返回 Docket，调用以下方法：
【1】apiInfo()方法中可以添加 api文档的基本信息（具体类型查看文档）；
【2】select()方法返回 ApiSelectorBuilder实例，用于过滤哪些 api需要显示；
【3】apis()方法中填写项目中 Controller类存放的路径；

最后 build()建立 Docket。

三、验证 Swagger2的 JSON格式文档

在application.yml中配置服务名为：swagger2-demo

server.contextPath=/swagger2-demo

maven构建并启动服务器。打开链接，会生成一个JSON格式的文档。这并不是那么容易理解，实际上Swagger已经提供该文档在其他第三方工具中使用，例如当今流行的 API管理工具，它提供了API网关、API缓存、API文档等功能。

四、验证 Swagger2 UI文档

打开链接在浏览器中来查看Swagger UI文档；

五、Swagger2 注解的使用

默认生成的 API文档很好，但是它们缺乏详细的 API级别信息。Swagger提供了一些注释，可以将这些详细信息添加到 api中。如。@Api我们可以添加这个注解在 Controller上，去添加一个基本的 Controller说明。

@Api(value = "Swagger2DemoRestController", description = "REST APIs related to Student Entity!!!!")
@RestController
public class Swagger2DemoRestController {
    //...
}

@ApiOperation and @ApiResponses我们添加这个注解到任何 Controller的 rest方法上来给方法添加基本的描述。例如：

@ApiOperation(value = "Get list of Students in the System ", response = Iterable.class, tags = "getStudents")
@ApiResponses(value = {
            @ApiResponse(code = 200, message = "Success|OK"),
            @ApiResponse(code = 401, message = "not authorized!"),
            @ApiResponse(code = 403, message = "forbidden!!!"),
            @ApiResponse(code = 404, message = "not found!!!") })
@RequestMapping(value = "/getStudents")
public List<Student> getStudents() {
    return students;
}

在这里，我们可以向方法中添加标签，来在 swagger-ui中添加一些分组。@ApiModelProperty这个注解用来在数据模型对象中的属性上添加一些描述，会在 Swagger UI中展示模型的属性。例如：

@ApiModelProperty(notes = "Name of the Student",name="name",required=true,value="test name")
private String name;

Controller 和 Model 类添加了swagger2注解之后，代码清单：Swagger2DemoRestController.java

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.example.springbootswagger2.model.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
@Api(value = "Swagger2DemoRestController", description = "REST Apis related to Student Entity!!!!")
@RestController
public class Swagger2DemoRestController {
    List<Student> students = new ArrayList<Student>();
    {
        students.add(new Student("Sajal", "IV", "India"));
        students.add(new Student("Lokesh", "V", "India"));
        students.add(new Student("Kajal", "III", "USA"));
        students.add(new Student("Sukesh", "VI", "USA"));
    }
    @ApiOperation(value = "Get list of Students in the System ", response = Iterable.class, tags = "getStudents")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Suceess|OK"),
            @ApiResponse(code = 401, message = "not authorized!"),
            @ApiResponse(code = 403, message = "forbidden!!!"),
            @ApiResponse(code = 404, message = "not found!!!") })
    @RequestMapping(value = "/getStudents")
    public List<Student> getStudents() {
        return students;
    }
    @ApiOperation(value = "Get specific Student in the System ", response = Student.class, tags = "getStudent")
    @RequestMapping(value = "/getStudent/{name}")
    public Student getStudent(@PathVariable(value = "name") String name) {
        return students.stream().filter(x -> x.getName().equalsIgnoreCase(name)).collect(Collectors.toList()).get(0);
    }
    @ApiOperation(value = "Get specific Student By Country in the System ", response = Student.class, tags = "getStudentByCountry")
    @RequestMapping(value = "/getStudentByCountry/{country}")
    public List<Student> getStudentByCountry(@PathVariable(value = "country") String country) {
        System.out.println("Searching Student in country : " + country);
        List<Student> studentsByCountry = students.stream().filter(x -> x.getCountry().equalsIgnoreCase(country))
                .collect(Collectors.toList());
        System.out.println(studentsByCountry);
        return studentsByCountry;
    }
    // @ApiOperation(value = "Get specific Student By Class in the System ",response = Student.class,tags="getStudentByClass")
    @RequestMapping(value = "/getStudentByClass/{cls}")
    public List<Student> getStudentByClass(@PathVariable(value = "cls") String cls) {
        return students.stream().filter(x -> x.getCls().equalsIgnoreCase(cls)).collect(Collectors.toList());
    }
}

Student.java 实体类

import io.swagger.annotations.ApiModelProperty;
public class Student
{
    @ApiModelProperty(notes = "Name of the Student",name="name",required=true,value="test name")
    private String name;
    @ApiModelProperty(notes = "Class of the Student",name="cls",required=true,value="test class")
    private String cls;
    @ApiModelProperty(notes = "Country of the Student",name="country",required=true,value="test country")
    private String country;
    public Student(String name, String cls, String country) {
        super();
        this.name = name;
        this.cls = cls;
        this.country = country;
    }
    public String getName() {
        return name;
    }
    public String getCls() {
        return cls;
    }
    public String getCountry() {
        return country;
    }
    @Override
    public String toString() {
        return "Student [name=" + name + ", cls=" + cls + ", country=" + country + "]";
    }
}

六、swagger-ui 展示

现在，当我们的 REST api得到适当的注释时，让我们看看最终的输出。打开http://localhost:8080/swagger2-demo/swagger-ui。在浏览器中查看 Swagger ui文档。

到此这篇关于SpringBoot Swagger2 接口规范的文章就介绍到这了,更多相关SpringBoot Swagger2 接口内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

Java 数据库时间返回前端显示错误(差8个小时)的解决方法
本文主要介绍了Java 数据库时间返回前端显示错误(差8个小时)的解决方法,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
2023-08-08
Spring中@RabbitHandler和@RabbitListener的区别详析
@RabbitHandler是用于处理消息的方法注解,它与@RabbitListener注解一起使用,这篇文章主要给大家介绍了关于Spring中@RabbitHandler和@RabbitListener区别的相关资料,需要的朋友可以参考下
2024-02-02
java生成饼图svg及JFreeChart生成svg图表
java生成饼图svg，代码实现感觉有点复杂，个人认为不如用JFreeChart，这篇文章主要介绍java生成饼图svg及JFreeChart生成svg图表，有需要的小伙伴可以参考下
2015-08-08
java实时监控文件行尾内容的实现
这篇文章主要介绍了java实时监控文件行尾内容的实现，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2020-02-02
Java使用位运算实现加减乘除详解
这篇文章主要为大家详细介绍了Java如何使用位运算实现加减乘除，文中的示例代码讲解详细，对我们深入了解Java有一定的帮助，感兴趣的可以了解一下
2023-05-05
Java中驼峰命名与下划线命名相互转换
这篇文章主要介绍了Java中驼峰命名与下划线命名相互转换，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2021-01-01
SWT(JFace)体验之StyledText类
有的时候Text需要实现这种那种的样式。先提供在不使用StyledText类的情况：
2009-06-06
解析Java中所有错误和异常的父类java.lang.Throwable
这篇文章主要介绍了Java中所有错误和异常的父类java.lang.Throwable,文章中简单地分析了其源码,说明在代码注释中,需要的朋友可以参考下
2016-03-03
Spring RedisTemplate 批量获取值的2种方式小结
这篇文章主要介绍了Spring RedisTemplate 批量获取值的2种方式小结，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2022-06-06
浅谈一下Java中的几种JVM级别的锁
这篇文章主要介绍了浅谈一下Java中的几种JVM级别的锁,当存在安全漏洞时，也必须有相应的防护措施。顺应这种趋势，虚拟"锁"被发明出来，以解决线程的安全问题。在这篇文章中，我们将研究多年来出现的 Java 中几种典型的 JVM 级锁,需要的朋友可以参考下
2023-08-08