Swagger 使用详解

最新推荐文章于 2024-06-18 09:42:23 发布

程序员学习圈

最新推荐文章于 2024-06-18 09:42:23 发布

阅读量968

点赞数 1

分类专栏： # Java相关文章标签： spring swagger springboot

本文链接：https://blog.csdn.net/Luomingkui1109/article/details/85763142

版权

Java相关专栏收录该内容

20 篇文章 1 订阅

订阅专栏

前言：作为一个以前后端分离为模式开发小组，我们每隔一段时间都进行这样一个场景：前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.."。可以看到在前后端沟通中出现了不少问题。

对于这样的问题,之前一直没有很好的解决方案，直到它的出现，没错...这就是我们今天要讨论的神器:swagger,一款致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器。

• swagger是什么？

• 为什么要使用swaager?

• 在项目中搭建和使用swagger示例

• 使用swagger需要注意的问题

• 总结和参考

1.swagger是什么？

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

这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

2.为什么要使用swaager?

2.1 对于后端开发人员来说

• 不用再手写WiKi接口拼大量的参数，避免手写错误

• 对代码侵入性低，采用全注解的方式，开发简单

• 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护

• 缺点：增加了开发成本，写接口还得再写一套参数配置

2.2 对于前端开发来说

• 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然

• 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

2.3 对于测试

• 对于某些没有前端界面UI的功能，可以用它来测试接口

• 操作简单，不用了解具体代码就可以操作

3.在项目中搭建和使用swagger示例

3.1 Maven

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

3.2 创建Swagger2配置类

在Application.java同级创建Swagger2的配置类Swagger2

package com.mkluo.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* @Auther: luomingkui
* @Date: 2019/1/4 10:52
* @Description:Swagger2配置类
* 在与spring boot集成时，放在与Application.java同级的目录下。
* 通过@Configuration注解，让Spring来加载该类配置。
* 再通过@EnableSwagger2注解来启用Swagger2。
*/

@Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */

    @Bean

    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mkluo.controller"))
                .paths(PathSelectors.any())
                .build().useDefaultResponseMessages(false);
    }



    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful API")
                .description("更多请关注https://blog.csdn.net/Luomingkui1109/article/details/85763142")
               .termsOfServiceUrl("https://blog.csdn.net/Luomingkui1109/article/details/85763142")
                .version("1.0")
                .build();
    }
}

如上代码所示，通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。

3.3 添加文档内容

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。

Swagger使用的注解及其说明：

- @Api()用于类：表示标识这个类是swagger的资源

- @ApiOperation()用于方法：表示一个http请求的操作

- @ApiParam()用于方法，参数，字段说明：表示对参数的添加元数据（说明或是否必填等）

- @ApiModel()用于：表示对类进行说明，用于参数用实体类接收

- @ApiModelProperty()用于方法，字段：表示对model属性的说明或者数据操作更改

- @ApiIgnore()用于类，方法，方法参数：表示这个方法或者类被忽略

- @ApiImplicitParam() 用于方法：表示单独的请求参数

- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

例子：

3.3.1 在SwaggerController类中：

package com.mkluo.controller;
import com.google.common.collect.Lists;
import com.mkluo.bean.ParkInfoQO;
import com.mkluo.bean.ParkInfoVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;

/**
* @Auther: luomingkui
* @Date: 2019/1/4 11:22
* @Description:
*/



@Api(tags = "测试Swagger接口", value = "test interface")
@RestController
@RequestMapping("/test")
public class SwaggerController {
    @ApiOperation(value = "测试swagger接口", notes = "测试swagger接口分组")
    @PostMapping("/swagger")
    public List<ParkInfoVo> selectByParkCode(@ApiParam(value = "城市（城市code和城市名称）") @RequestBody ParkInfoQO parkInfoQO){
        List<ParkInfoVo> list = Lists.newArrayList();
        ParkInfoVo pk = new ParkInfoVo();
        pk.setParkCode("110110");
        pk.setParkName("北京昌平园区");
        pk.setCity("北京");
        pk.setArchitectureArea("10000平米");
        list.add(pk);
        return list;
    }
}

3.3.2 在ParkInfoQO类中

package com.mkluo.bean;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
* @Auther: luomingkui
* @Date: 2019/1/4 11:19
* @Description:
*/

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "ParkInfoQO",description = "城市名code和城市名称")
public class ParkInfoQO {
    @ApiModelProperty(value = "城市code",example = "abc",required = false)
    private String orgCode;
    @ApiModelProperty(value = "城市名称",example = "北京",required = false)
    private String city;
}

3.3.3 在ParkInfoVo类中

package com.mkluo.bean;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
* @Auther: luomingkui
* @Date: 2019/1/4 11:20
* @Description:
*/

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "ParkInfoDO",description = "园区的详细信息")
public class ParkInfoVo {
    /**园区编码*/
    @ApiModelProperty(value = "园区编码")
    private String parkCode;

    /**园区名称*/
    @ApiModelProperty(value = "园区名称")
    private String parkName;

    /**园区面积*/
    @ApiModelProperty(value = "园区面积")
    private String architectureArea;

    @ApiModelProperty(value = "所属城市")
    private String city;
}

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html

3.4 最终效果：

4.使用swagger需要注意的问题

• 对于只有一个HttpServletRequest参数的方法,如果参数小于5个，推荐使用 @ApiImplicitParams的方式单独封装每一个参数；如果参数大于5个，采用定义一个对象去封装所有参数的属性，然后使用@APiParam的方式

• 默认的访问地址：ip:port/swagger-ui.html#/,但是在shiro中,会拦截所有的请求，必须加上默认访问路径（比如项目中，就是ip:port/context/swagger-ui.html#/），然后登陆后才可以看到

• 在GET请求中，参数在Body体里面,不能使用@RequestBody。在POST请求，可以使用@RequestBody和@RequestParam，如果使用@RequestBody，对于参数转化的配置必须统一

• controller必须指定请求类型，否则swagger会把所有的类型(6种)都生成出来

• swagger在生产环境不能对外暴露,可以使用@Profile({“dev”, “prod”,“pre”})指定可以使用的环境

5.总结和参考

5.1 总结

swagger作为一款辅助性的工具，能大大提升我们的和前端的沟通效率,接口是一个非常重要的传递数据的媒介，每个接口的签名、方法参数都非常重要。一个良好的文档非常重要，如果采用手写的方式非常容易拼写错误，而swagger可以自动化生成参数文档，这一切都加快了我们的沟通效率。并且可以替代postman的作用。实在是开发编程必备良品啊。

5.2 参考

Swagger官网：http://swagger.io/

Github：https://github.com/swagger-api/swagger-core/wiki/Annotations

Spring Boot & Swagger UI ： http://fruzenshtein.com/spring-boot-swagger-ui/

代码示例： https://github.com/luomingkui/springboot

程序员学习圈

关注

1
点赞
踩
4

收藏

觉得还不错? 一键收藏
打赏
0
评论
Swagger 使用详解

前言：作为一个以前后端分离为模式开发小组，我们每隔一段时间都进行这样一个场景：前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.."。可以看到在前后端沟通中出现了不少问题。对于这样的问题,之前一直没有很好的解决方案，直到它的出现，没错...这就是我们今天要讨论的神器:swagger,一款致力于解决接口规范化、...
复制链接

扫一扫