Spring Boot测试使用 Swagger2 构建RESTful API

Swagger2介绍

1.官网

首先我们先去看看swagger2的官网
https://swagger.io/

2.应用场景（抄的）

    由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。

–

    Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示：

3. 展示图：

我这里只是一个简单的小demo，另一篇写关于其常用注解：
!

4.代码部分

下面直接撸代码：

• 1.创建spring Boot项目

刚学Spring boot的看我这篇博客：

https://blog.csdn.net/qq_28643817/article/details/83791310

• 2.添加meavn依赖

 <!--swagger -->   
 <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>

• 3.创建swagger2工具类

package com.learn.test.utils;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

//注解开启 swagger2 功能
@EnableSwagger2
//注解标示,这是一个配置类,@Configuation注解包含了@Component注解
//可以不用在使用@Component注解标记这是个bean了,
@Configuration
public class Swagger2 {

    /**
     * 通过 createRestApi函数来构建一个DocketBean
     * 函数名,可以随意命名,喜欢什么命名就什么命名
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
                .select()
                //控制暴露出去的路径下的实例
                //如果某个接口不想暴露,可以使用以下注解
                //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下
                .apis(RequestHandlerSelectors.basePackage("com.learn.test.controller"))
                .paths(PathSelectors.any())
                .build();
    }


    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //创建人
                .contact("陈大壮")
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

• 4创建controller层测试

package com.learn.test.controller;


import com.learn.test.model.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;


@SpringBootApplication(scanBasePackages = {"com"})
//该注解包含了@Controller和@ResponseBody两个注解
@RestController
public class swaggerController {

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

    /**
     * 以下函数的注释,不增加注解了,将在下面统一做描述
     */


    @ApiOperation(value = "测试post请求", notes = "注意事项")
    @ApiImplicitParam(dataType = "User", name = "user", value = "用户信息", required = true)
    @RequestMapping(value = "/testPost", method = RequestMethod.POST)
    public String testPost(@RequestBody User user) {
        return "success";
    }


    @ApiOperation(value = "测试get请求", notes = "注意事项")
    @ApiImplicitParam(name = "id", value = "用户id", dataType = "String", paramType = "path")
    @RequestMapping(value = "/testGet/{id}", method = RequestMethod.GET)
    public String testGet(@PathVariable String id) {
        return id;
    }

    @ApiOperation(value = "测试组合注解", notes = "注意事项")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "User", name = "user", value = "用户信息", required = true, paramType = "body"),
            @ApiImplicitParam(dataType = "string", name = "id", value = "用户id", required = true, paramType = "path")
    })
    @RequestMapping(value = "/joinAnnotation/{id}", method = RequestMethod.POST)
    public User joinAnnotation(@PathVariable String id, @RequestBody User user) {
        return user;
    }

    @ApiIgnore
    public String testIgnore() {
        return "success";
    }
}

• 5.运行Spring Boot项目

• 6.出现问题及解决方案

测试下本地url：
http://localhost:8080/swagger-ui.html#/
出现问题：
No operations defined in spec!
如下图所示：

是有可能你的swaggerUtil没有扫描到你的注解
在这里进行更改就好了

可以点击进行对应的测试：

好啦，以上就是我分享的全部内容啦，请大家多多指教！【ヾ(•ω•`)o~】