快速入门 Swagger

快速入门 Swagger

1. 概述

目前，大多数系统都采用前后端分离。一般都是前后端先行沟通设计接口文档，前后端同时进行开发工作。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

2. 快速入门 Swagger

在 springboot maven项目pom.xml 文件中，引入相关依赖。

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- 引入 Swagger 依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- 引入 Swagger UI 依赖，以实现 API 接口的 UI 界面 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

创建 SwaggerConfiguration 配置类，用于配置 Swagger 。代码如下：

package com.gl.lab01.swagger.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 springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 // 标记项目启用 Swagger API 接口文档
public class SwaggerConfiguration {
    
    

    @Bean
    public Docket createRestApi() {
    
    
        // 创建 Docket 对象
        return new Docket(DocumentationType.SWAGGER_2) // 文档类型，使用 Swagger2
                .apiInfo(this.apiInfo()) // 设置 API 信息
                // 扫描 Controller 包路径，获得 API 接口
                .select()
                // 项目的controller包路径
                .apis(RequestHandlerSelectors.basePackage("com.gl.lab01.swagger.controller"))
                .paths(PathSelectors.any())
                // 构建出 Docket 对象
                .build();
    }

    /**
     * 创建 API 信息
     */
    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                .title("测试接口文档示例")
                .description("描述")
                .version("1.0.0") // 版本号
                .contact(new Contact("name111", "http://www.baidu.cn", "666666.qq@com")) // 联系人
                .build();
    }

}

Application.java 类：

@SpringBootApplication
public class Application {
    
    

    public static void main(String[] args) {
    
    
        SpringApplication.run(Application.class, args);
    }

}

Controller：

package com.gl.lab01.swagger.controller;

import com.gl.lab01.swagger.dto.UserAddDTO;
import com.gl.lab01.swagger.dto.UserUpdateDTO;
import com.gl.lab01.swagger.vo.UserVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

@RestController
@RequestMapping("/users")
@Api(tags = "用户 API 接口")
public class UserController {
    
    

    @GetMapping("/list")
    @ApiOperation(value = "查询用户列表", notes = "所以返回用户全列表")
    public List<UserVO> list() {
    
    
        // 查询列表
        List<UserVO> result = new ArrayList<>();
        result.add(new UserVO().setId(1).setUsername("helloWord"));
        result.add(new UserVO().setId(2).setUsername("helloWord1"));
        result.add(new UserVO().setId(3).setUsername("helloWord2"));
        // 返回列表
        return result;
    }

    @GetMapping("/get")
    @ApiOperation("获得指定用户编号的用户")
    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "666")
    public UserVO get(@RequestParam("id") Integer id) {
    
    
        // 查询并返回用户
        return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());
    }

    @PostMapping("add")
    @ApiOperation("添加用户")
    public Integer add(UserAddDTO addDTO) {
    
    
        // 插入用户记录，返回编号
        Integer returnId = UUID.randomUUID().hashCode();
        // 返回用户编号
        return returnId;
    }

    @PostMapping("/update")
    @ApiOperation("更新指定用户编号的用户")
    public Boolean update(UserUpdateDTO updateDTO) {
    
    
        // 更新用户记录
        Boolean success = true;
        // 返回更新是否成功
        return success;
    }

    @PostMapping("/delete")
    @ApiOperation(value = "删除指定用户编号的用户")
    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
    public Boolean delete(@RequestParam("id") Integer id) {
    
    
        // 删除用户记录
        Boolean success = false;
        // 返回是否更新成功
        return success;
    }

}

执行 Application 启动项目。然后浏览器访问 http://127.0.0.1:8080/swagger-ui.html 地址，就可以看到 Swagger 生成的 API 接口文档。如下图所示：