一文浅谈，Spring Boot集成Swagger UI

前言

相信大部分的开发人员都或多或少地被接口文档折磨过。后端人员接口开发完成，又需编写及维护接口文档会耗费不少精力，经常来不及更新。Swagger基于注解进行开发，提供了一个灵活的接口文档模板。更新运行编译后，直接可以在线预览，避免了重复修改的问题，下面开始介绍Swagger UI。

什么是Swagger UI

Swagger UI是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。主要作用是：接口的文档在线自动生成和在线预览，可以进行业务功能的测试。

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

Swagger UI的使用

引入依赖

Maven方式引入所需要的依赖包，具体信息如下：

  
        
            io.springfox
            springfox-swagger2
            2.5.0
        
        
        
            io.springfox
            springfox-swagger-ui
            2.5.0

Swagger UI 配置类

Swagger UI 配置类首先是提供了一个强大的构造器，用于创建API。其中构建API的基本信息有页面的标题、版本号、接口文档的描述、服务条款的地址、contact、许可信息、许可信息地址等，其中contact里面可以其他更多的信息。

ApiInfo：构建Api文档的详细信息函数。
Docket:Swagger UI返回的API文档信息。

其中主要属性有：

apiInfo()是apiInfo的基本信息。
select()Api 选择器生成器。
apis为当前请求处理程序选择器所需要进行API文档的包路径。
paths路径选择器为any任何包都处理。

public class SwaggerConfig {
   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .select()
               //为当前包路径
               .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
               .paths(PathSelectors.any())
               .build();
   }
   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("Spring Boot 使用 Swagger2 构建RESTful API")
               .contact(new Contact("Bryan", "http://blog.bianxh.top/", ""))
               .version("1.0")
               .description("API 描述")
               .build();
   }

Swagger UI 注解

@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。

常用的参数：

    paramType：指定参数放在哪个地方
    header：请求参数放置于Request Header，使用@RequestHeader获取
    query：请求参数放置于请求地址，使用@RequestParam获取
    path：（用于restful接口）-->请求参数的获取：@PathVariable
    body：（不常用）
    form（不常用）
    name：参数名
    dataType：参数类型
    required：参数是否必须传(true | false)
    value：说明参数的意思
    defaultValue：参数的默认值

@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息。其中ApiResponse包含三个属性

    code：数字，例如200 请求成功
    message：信息，例如"请求成功"
    response：请求成功返回的数据信息

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性

源码

pom.xml

<?xml version="1.0" encoding="UTF-8"?>

    4.0.0
    
        org.springframework.boot
        spring-boot-starter-parent
        2.3.0.RELEASE
         
    
    com.example
    swagger
    0.0.1-SNAPSHOT
    swagger
    Demo project for Spring Boot and MyBatis and Swagger

    
        1.8
    

    
        
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            org.apache.commons
            commons-lang3
            3.7
        
        

        
        
            mysql
            mysql-connector-java
            runtime
        
        
        
            org.mybatis.spring.boot
            mybatis-spring-boot-starter
            2.1.1
        
        
        
            com.alibaba
            druid
            1.1.11
        
        

        
        
            org.springframework.boot
            spring-boot-starter-test
            test
            
                
                    org.junit.vintage
                    junit-vintage-engine
                
            
        
        
        
            junit
            junit
            4.12
            test
        
        


        
        
            io.springfox
            springfox-swagger2
            2.5.0
        
        
        
            io.springfox
            springfox-swagger-ui
            2.5.0
        
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin

application.properties

server.port=8888

# mysql
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/test?useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull
spring.datasource.username=test
spring.datasource.password=123456
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.type=com.alibaba.druid.pool.DruidDataSource

mybatis.mapper-locations=classpath*:mapper/**/*.xml

SwaggerConfig

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

/**
 * @ClassName SwaggerConfig
 * @Description: SwaggerConfig配置
 * @Date 2020/8/13
 * @Version V1.0
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
    * @ClassName 创建Docket
    * @Description: 创建Docket
    * @Date 2020/8/13
    * @Version V1.0
    **/
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * @ClassName ApiInfo
     * @Description: ApiInfo
     * @Date 2020/8/13
     * @Version V1.0
     **/
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("头条作者")
                .contact(new Contact("头条","https://www.toutiao.com/", ""))
                .version("1.0")
                .description(" API 描述")
                .build();
    }
}

DemoSwaggerApplication

package com.example.demo;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @ClassName Swagger UI集成测试
 * @Description: Swagger UI集成测试启动类
 * @Date 2020/8/13
 * @Version V1.0
 **/
@SpringBootApplication
@MapperScan("com.example.demo.mapper")
public class DemoSwaggerApplication {

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

}

UserController

package com.example.demo.controller;

import com.example.demo.module.User;
import com.example.demo.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

import javax.annotation.Resource;
import java.util.List;

/**
 * @ClassName UserController
 * @Description: 用户管理
 * @Date 2020/8/13
 * @Version V1.0
 **/
@Api(description = "用户管理")
@RequestMapping("user")
@Controller
public class UserController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "获取所有用户")
    @RequestMapping(value = "getAllUser",method = RequestMethod.GET)
    @ResponseBody
    public List getAllUser(){
        return userService.getAllUser();
    }
}

使用Swagger UI

打开API

在浏览器输入：http://localhost:8888/swagger-ui.html 出现接口文档信息，即Swagger文档集成成功

测试接口

选择user/getAllUser这个接口，获取所有用户信息，可以看到请求方式是GET请求。请求参数为空，返回的Model是User，

点击Try it out 。接口自动请求，返回请求参数和返回的值信息。请求成功，返回状态为200。返回正常的List数据信息。

结语

这样Swagger与Spring Boot集成成功啦。更多的测试大家可以深入研究一下Swagger相关信息，相信一定会有新大陆发现的。

展开阅读全文

页面更新：2024-05-13

标签：在线基本信息注解路径属性接口作用常用参数文档地址测试方法用户科技信息

1 2 3 4 5