学会Swagger，接口调试不再烦恼

程序员文章站 2022-06-22 09:53:49

前言最近在做一个基于微服务的在线教育项目，由于前后端都是要自己写，所以接口的调试便成了一个比较重要的问题。尤其是在自己一个人开发或者的时候作用显得尤为重要。在写项目的时候我总是喜欢先写后端接口，然后再去处理前端，最后进行整合联调。大部分的人的开发流程也应该是这样的。在开发的过程中有一个问题一直很困扰我们，**每当我们写完一个接口想要测试它是否按要求返回对象的数据，**以前的做法往往是启动服务，然后在浏览输入对应的接口地址和参数进行数据请求。这种情况下，当接口没有请求传入的参数或者是参数只有一两个的时候...

前言

最近在做一个基于微服务的在线教育项目，由于前后端都是要自己写，所以接口的调试便成了一个比较重要的问题。尤其是在自己一个人开发或者的时候作用显得尤为重要。在写项目的时候我总是喜欢先写后端接口，然后再去处理前端，最后进行整合联调。

大部分的人的开发流程也应该是这样的。在开发的过程中有一个问题一直很困扰我们，**每当我们写完一个接口想要测试它是否按要求返回对象的数据，**以前的做法往往是启动服务，然后在浏览输入对应的接口地址和参数进行数据请求。

这种情况下，当接口没有请求传入的参数或者是参数只有一两个的时候还好，但是当传参多了之后，你会觉得很麻烦。

从另一方面讲，但后端写得接口很多的，在写完之后需要进行修改或者调试的时候，你会发现是自己的controller非常的乱。

再这样的情况下，一款好用的API框架—Swgger稳健上位!

什么是Swagger

学会Swagger，接口调试不再烦恼
Swgger是一款可用于设计、构建、文档化并且执行API的框架。是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

这是官网对Swagger的介绍：
Swagger UI允许任何人（无论您是开发团队还是最终用户）都可以可视化API资源并与之交互，而无需任何实现逻辑。它是根据您的OpenAPI（以前称为Swagger）规范自动生成的，具有可视化文档，可轻松实现后端实现和客户端使用。

那什么又是RESTful风格呢？
百度百科是这样说的—restful是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

我们可以理解为：它是一种互联网应用程序的API设计理念：URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。RESTful可以通过一套统一的接口为 Web，iOS和Android提供服务

Swagger的作用

Swagger可以轻松的创建一个API文档，前后端分离开发模式中，api文档是最好的沟通方式。

Swagger使用方法

1.引入依赖

    <!--swagger-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <scope>provided </scope>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <scope>provided </scope>
    </dependency>

2.创建swagger的配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("分组名称")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("你的借口文档名称")
                .description("你的接口文档描述")
                .version("1.0")
                .contact(new Contact("Helen", "http://atguigu.com", "55317332@qq.com"))
                .build();
    }
}

3.在对应的要使用的模块中引入配置

因为APi接口在整个的后端开发中都会使用，所以我们一般是使用在父项目（主项目）中配置Swagger文件，然后在子项目中在pom.xml中引入的方式进行使用。

4.在controller中写对应的接口注解

Swagger的六个注解：

@APi： 通常为一个controller做注解，说明一个controller的职能。

@ApiOperation: 通常为一个接口做注解，说明接口的职能。

@APIImplicitParams： 通常用来包含接口的一组参数注解，可以将其简单的理解为参数注解的集合。

@APIImplicitParam： 用在@APIImplicitParams注解中，说明一个请求的各个方面。
paramType，参数所放置的地方。
name：参数名
dataType：参数类型
required：参数是否必传
value：参数值
defaultValue：默认的参数值

@ApiResponses: 通常用来包含接口的一组响应注解，可以将其简单的理解为相应注解的组合。

@ApiResponse： 用在@ApiResponses中，一般用于表达一个错误的信息。
code：即一个httpCode数字，例如：404
message：信息，例如’请求参数没有填好’

例如：

@Api(description="讲师管理")
@RestController
@RequestMapping("/admin/edu/teacher")
public class TeacherAdminController {

    @Autowired
    private TeacherService teacherService;
    @ApiOperation(value = "所有讲师列表")
    @GetMapping
    public List<Teacher> list(){
        return teacherService.list(null);
    }

    @ApiOperation(value = "根据ID删除讲师")
    @DeleteMapping("{id}")
    public boolean removeById(
            @ApiParam(name = "id", value = "讲师ID", required = true)
            @PathVariable String id){
        return teacherService.removeById(id);
    }
}