Swagger3 Get Start!!

itbear
812 阅读7分钟

Swagger 是什么？

Swagger 是什么？维基百科上是这样介绍的：

Swagger是一种接口描述语言，用于描述使用JSON表示的RESTful API 。

这里提到了JSON和RESTful 两大名词，JSON的全称为(JavaScript Object Notation) JavaScript对象表示法，它是一种轻量级的数据交换格式，采用完全独立于编程语言的文本格式来存储和表示数据。而RESTful 则表示一种规范，它的全称是（**Representational State Transfer）**表述性状态转换，可以通俗的理解为：一组具有约束条件和原则的规范。

  • RESTFUL API 就是经过一组确定好的具有约束行为和统一原则的规范来规定 API的书写规则、命名规则、请求规则、响应规则的一种表述性方式。通过这个方式可以理解 API 所代表的的业务场景和返回字段的含义。

回到Swagger当中，它其实就是一款可以简化 API开发的工具，并且根据UI界面生成一个自动化的接口文档地址，便于项目的测试与接口的管理。

为什么使用 Swagger？

1. 配置简单、快速上手

例如想要在SpringBoot工程中使用Swagger，不用编写任何繁琐的xml配置，只需要将指定好的依赖导入pom.xml中即可，并且再根据一个简单的Swagger配置类即可使用。

2. 界面友好、通俗易懂

Swagger 通过内置 html 解析器的方式来实现将 RESTFUL API数据显示在界面上供开发者查看，界面样式既简洁又美观，开发者可以很直观地看到自己所编写的 RESTFUL API 的请求方式、请求参数、返回格式以及所属业务组，如下图所示。

3. 快速测试、便于交互

例如在开发SpringBoot项目的时候，在测试接口时需要用到浏览器（默认只支持GET请求）或者postman，前者测试能力有限，后者又太繁琐，每次都需要切换不同的请求和URL地址，使得开发效率的降低，而使用了Swagger之后，只需要在响应的类和方法上使用注解进行说明，Swagger就会生成一份完整的接口文档和注释说明。

Swagger 的优点

  • 格式导出灵活 : 支持 Json 和 yml 来编写 API 文档，并且支持导出为 json、yml、markdown 等格式。
  • 跨语言支持性 : 只针对 API，而不针对特定语言的 API，很多自动生成 API 的工具基本都是只针对特定的 API。
  • 界面清晰易懂 : 界面清晰，无论是编辑器的实时展示还是 Swagg-UI 界面的展示都十分人性化，简单明了。
  • **测试方便：**Swagger要比浏览器、Postman之类的工具方便很多，只需启动项目访问界面测试相对应的接口即可。

Swagger 的缺点

  • 无法自定义格式: Swagger-UI 封装好了一套 Html 模板，任何 RESTFUL API 的展示形式只能遵循其格式，不能灵活修改。
  • 官方文档不全面 : Swagger 官方针对不同的模块提供了不同的介绍文档，但是缺乏系统的介绍，不利于入门学习。

Get Start

下面基于SpringBoot项目来做一个Swagger 3.0快速搭建工程。

版本配置

  • jdk 1.8
  • SpringBoot
  • Swagger 3.0
  • lombok 1.8.16
  • Maven 3.6.3

构建SpringBoot项目

  • 依次点击File->New->Project->Spring Initalizr

image.png

包名和项目名分别为com.swagger3-swagger3

image.png

分别勾选Lombok和Web依赖。

引入Swagger3依赖

在最新版本的Swagger3当中，只需要导入官方提供的springfox-Starter依赖即可（旧版本需要两个不同的依赖）

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

编写Swagger配置

  • 创建一SwaggerConfiguration类
package com.swagger3.configuration;

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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class SwaggerConfiguration {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
            .apiInfo(info())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.swagger3.controller"))
            .paths(PathSelectors.any())
            .build();
    }
    private ApiInfo info() {
        return new ApiInfoBuilder()
            .title("自定义Swagger-UI接口文档")
            .description("自定义文档")
            .contact(new Contact("Bear","http://www.yuque.com/bearpessimist","1942496795@qq.com"))
            .version("1.0")
            .license("Apache-2.0")
            .build();
    }
}

Swagger的核心配置只有这两个方法，第一个方法是Swagger的核心配置，用于指定文档的类型和接口包的扫描。第二个方法是文档和作者的信息，内容可选。

  • 代码解释：

    • @Configuration表示这是个配置类，将此类添加到Spring容器当中，类似于文件中的
    • @EnableOpenApi 表示开启Swagger的功能，代替了旧版本注解@EnableSwagger2
    • @Bean则是为docket方法装配属性，和标签一样。
    • DocumentationType.OAS_30 是指定文档的属性为3的版本
    • .apiInfo(info()) 则是构造第二个方法作者的信息。select()是一个连接方法，用于继续构造下面的内容
    • apis和paths是核心的配置，表示扫描指定包中的接口，PathSelectors.any()则为扫描任意路径的接口到Swagger中，如果不配置则会没有任何的显示。.build()方法则指定方法构造结束。
    • 第二个方法返回了一个ApiInfoBuilder对象来构造信息，title是文档的标题，description就是文档的描述，contact中为作者的名称、网站、邮箱地址。version和license为指定文档版本和协议类型。

在做完以上的配置之后就可以启动项目进行测试了，下面新建一个接口进行测试。

新建一个HelloController

package com.swagger3.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping(path = "/hello")
    public String hello() {
        return "Hello,Swagger3";
    }
}

image.png

上图标注的部分依次为文档的标题、文档生成地址、描述、作者名称和网站、协议、扫描的接口。

接口的测试

从上图可以看到UI界面最核心的地方就是下面的接口测试，这也是Swagger存在的作用。方便接口文档的管理与测试。下面来演示接口的测试

  • 点开HelloController

image.png

整个接口测试界面对应着五个部分，分别为接口的类名称，发送请求和接口名称，参数区、响应区。测试的方法就是点击右边的Try it out进入点击Execute执行即可，如下图。

image.png

如果没有任何参数的话可以直接点击Execute执行，结果呈现就如下面这样

image.png

其中画红线的地方就是结果的响应体，也就是请求服务端的数据，最顶部的Curl是生成可以在cmd命令行执行的参数地址，Request URL则是项目的接口地址，Code是响应状态码，200表示请求成功，Response headers里是一些响应头的参数内容。

  • 可以看到对接口的测试要即为方便（反正总比打开浏览器或者postman感觉要好），无参的接口可以直接通过Execute来执行，那么带参的接口如何处理呢？下面根据用户登录接口来演示

  • 新建一个User的实体类，提供两个成员属性

package com.swagger3.entities;

import lombok.Data;

@Data
public class User {
    private String username;
    private String password;
}
  • 创建一个UserController返回一个User对象测试
@RestController
public class UserController {

    @PostMapping("/login")
    public User login(String username,String password) {
        User user = new User();
        user.setUsername(username);
        user.setPassword(password);
        return user;
    }
}

方法参数中定义了一个用户名和密码，代表提交的请求参数，并且new一个User对象将参数接收

  • 启动项目可以看到如下界面

image.png

在参数区分别提供了两个输入框，分别对应着接口中的两个参数，点击Try it out后需要在输入框中输入对应的值才可以点击Execute执行结果，例如将username设置为Bear，password为123。下面查看响应的结果

image.png

  • 响应结果

image.png

以上就是对Swagger 3.0进行的一个快速入门，其余更多的使用方式已经在我Swagger2.9.2 中写成了文档，不过2版和3版有些许差异，一是依赖的更换、二是注解的变更，但旧版注解也可以利用到新版注解当中。

avatar
文章
阅读
粉丝