Swagger2 整合springboot 2.X

作者: 小土豆哥哥 | 来源:发表于2019-01-28 11:13 被阅读114次

swagger是什么？

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

swagger优点？

完全实现了前后端交互的实时性，可以随时对更改的接口文档进行查看，防止出现调用接口失误。
前端人员可以自行在网站上进行测试
可以自动生成你想要的语言模式，便于切换

框架说明及使用

现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

Swagger Codegen
通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI
提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor
类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector
感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Hub
集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

注：Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

Springboot 2.X 整合 Swagger2

添加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>

@Configuration
@EnableSwagger2
public class Swagger2Config {

/**
 * 创建swagger ui的摘要
 *
 * @return
 */
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            // 扫描的class的包路径
.apis(RequestHandlerSelectors.basePackage("com.wangyq.boot.controller"))
            // 只扫描类上有API注解的class
            // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
            // 只扫描方法上有ApiOperation注解的方法                         //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build();
}

/**
 * swagger ui的标题信息
 *
 * @return
 */
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("标题")
            .description("副标题")
            .version("1.0")
            .build();

}

}

添加注解


@Controller
@RequestMapping("/test")
@Api(value = "/test", description = "Operations about test", tags = "测试管理")
public class TestController extends BaseController {
    private Logger logger = LoggerFactory.getLogger(TestController.class);

    @RequestMapping(value = "/testRateLimit5", method = {RequestMethod.GET})
    @ResponseBody
    @RateLimit(limitNum = 2)
    @ApiOperation(value = "测试接口限流", notes = "每秒钟限流5 token", httpMethod = "GET")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "data", value = "返回的数据对象", dataType = "Object"),
            @ApiImplicitParam(name = "msg", value = "消息", dataType = "String"),
            @ApiImplicitParam(name = "code", value = "状态码", dataType = "Integer")
    })
    public Result testRateLimit5() {
        logger.info("调用了 testRateLimit5 方法");
        return ResultUtil.success("调用了 testRateLimit5 方法！");
    }

    @GetMapping(value = "/testRateLimit10")
    @RateLimit(limitNum = 10)
    public Result testRateLimit10() {
        logger.info("调用了 testRateLimit10 方法");
        return ResultUtil.success("调用了 testRateLimit10 方法！");
    }
}

启动springboot项目，访问http://[ip]:[port]/swagger-ui.html，如：http://localhost:8080/swagger-ui.html

Image.png

swagger在spring中常用注解说明

Api、ApiIgnore
ApiModel
ApiModelProperty
ApiOperation
ApiParam、ApiImplicitParam、ApiImplicitParams
ApiResponse
ApiResponses
ResponseHeader

@Api
Api注解用于类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源。与Controller注解并列使用。
@Api(value = "/test", description = "Operations about test", tags = "测试管理") @Controller
@Api.png

ApiModel
ApiModel注解用于表示对类进行说明，描述一个Model的信息，表示参数用实体类接收。
ApiModelProperty
ApiModelProperty注解用于方法、字段，表示对model属性的说明或者数据操作更改，配合ApiModel一起使用。
ApiOperation
ApiOperation注解，用在方法上，说明方法的作用，与Controller中的方法并列使用。

ApiOperation.png