欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  科技

学会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);
    }
}
5.为了能使得自己的配置起作用,需要在启动类上添加上报扫描注解

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


6.启动项目,访问对应项目对应端口下的swagger-ui.html,即可得到对应的接口调试文档和接口,就可以进行调试等操作。

例如我的项目在本地,端口号为8001,那么在项目启动之后访问地址:http://localhost:8001/swagger-ui.html,就可以得到如下界面:


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


里面有编写的各个controller和各个controller下的对应接口,对于需要传入参数的,也会有对应的阐述参数输入框,输入对应的参数就可以得到对应的返回结果了。


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


本文地址:https://blog.csdn.net/mzc_love/article/details/110457400