都说Swagger很好用，今天亲身体验了一把，结果是这样

最新推荐文章于 2024-08-05 14:04:09 发布

goody9807

最新推荐文章于 2024-08-05 14:04:09 发布

阅读量1.9k

点赞数 1

分类专栏：实用工具文章标签： java

本文链接：https://blog.csdn.net/goody9807/article/details/123758002

版权

实用工具专栏收录该内容

6 篇文章 0 订阅

订阅专栏

导言

听说兄弟开发部门的团队开发效率很高，于是找了技术Leader去交流取取经。在沟通过程中，听大牛最得意的一个地方就是使用了Swagger这个工具，他说大大提高了前后端联调的效率。抱着猎奇的心态，于是亲自手撸了一把Swagger，结果却是这样的......

初识Swagger

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

为什么要用Swagger呢？

1.后端开发的痛点

每次新需求就要提供很多的接口给前端，另外还需要按照一定的标准写接口文档，对于每个字段的说明都要写清楚。这个不算什么，就是随着业务需求的日益迭代，接口会经常修改，那随之发生的是接口文档也随之变更。有的时候修改了代码，忘记修改文档了，就会受到前端开发人员的问责。

2.前端开发的痛点

由于每次迭代都是后端先行，那工期十分紧迫，有时候后端开发延期，给前端留的时间不多，那么前端就会很紧张。有的同学说可以定义假接口。是的，没错! 但是，假接口也需要数据，有的复杂接口构造数据也很费时。

3.Swagger的到来

对于后端开发而言：

不用再手写WiKi接口拼大量的参数，避免手写错误
对代码侵入性低，采用全注解的方式，开发简单
方法参数名修改、增加、减少参数都可以直接生效，不用手动维护

对于前端开发而言：

后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

如何使用Swagger呢

1.引入swagger的依赖

<!--引入swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2.增加Swagger启动配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //添加ApiOperiation注解的被扫描
                .paths(PathSelectors.any())
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(”goody9807的CSDN博客“).description(”swagger的接入")
                .version("1.0").build();
    }

}

3.接口定义中设置

@ApiOperation("goody9807的CSDN博客")
@PostMapping("/goody9807")
@ResponseBody
public String goody9807(@ApiParam("点个关注和收藏再走吧")String username){
    return username;
}

4.Swagger常用注解

Swagger的局限

说到这里，要是不写这一节那很多朋友都会说我是标题党，但是在使用过程中我们发现了一些局限性，也许在Swagger的后续迭代中会解决吧！

1.代码中的注解编写要花费大量的时间

为了能够实现自动生成接口文档，需要在代码中提前写大量的注解，生成的接口文档越清晰，写的注解越多，要求每个参数响应的属性都要标明含义。另外接口变更需要同步修改Swagger的相关定义注解。

2.对于返回结果不能添加说明

对于返回结果不能添加说明或者实现这个功能非常麻烦。虽然 Swagger 有 @ApiResponse
注解用来说明返回结果，但是这个使用并不方便，而且如果返回的并不是对象的时候(如 Map),就无法实现给每一个返回字段的说明。如果将所有的返回结果都是用对象封装，然后添加注解，这又是一个非常大的工作量。

说了这么多，到底是推荐大家是否使用Swagger吗？我觉得这就要根据实际情况而定，大家具体开发的是什么项目？前端同学是否对接口文档有比较高的要求，另外如果是新的项目还是老的项目，我觉得可以尝试用一下，看看ROI是否符合预期，最后祝大家全年无BUG！