源码Gitub地址:https://github.com/heibaiying/spring-samples-for-all

一、Springfox 与 Swagger 简介

1.1 Springfox

Springfox 是一个开源的API Doc的框架, 它的前身是swagger-springmvc,能够完美的支持springmvc,可以将spring 接口方法自动转换为接口文档。 目前spring fox 正致力于对更多JSON API规范和标准的扩展和支持,例如:swaggerRAMLjsonapi

1.2 Swagger

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,支持从整个API生命周期(从设计和文档到测试和部署)的开发。

swagger 是一个综合的开源项目,包含swagger-coreswagger-uiswagger-codegenswagger-editor等多个子项目。

  • swagger-core:Swagger Core是OpenAPI规范(以前称为Swagger规范)的Java实现
  • swagger-ui:依据可视化文档,提供与API资源的可视化交互。
  • swagger-codegen:开源的代码生成器,根据Swagger定义的RESTful API可以自动建立服务端和客户端的连接。
  • swagger-editor:开源的api文档编辑器。

下图为swagger-ui 提供的文档可视化界面示例:

1.3 OpenApi、Swagger、Springfox的关系

Swagger Core 是 OpenApi 规范(以前称为Swagger规范)的Java 实现,而 Springfox 提供 Swagger 与 spring 的集成支持

二、spring boot 集成 swagger 2.0

2.1 导入项目相关依赖

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.2 进行swagger个性化配置、并用@EnableSwagger2开启Swagger支持

这里需要说明的是swagger虽然是一个非常直观易用的接口调试插件,但是有可能导致接口信息泄露的危险,所以建议在开发环境和测试环境开启,在生产环境关闭。这里一共给出三种Swagger开关切换的方法:

  1. 如下面代码所示,在配置文件中配置自定义的开关参数,并在创建Docket时候,在链式调用的enable()方法中传入;

  2. SwaggerConfig配置类上添加@Profile({"dev","test"})注解,指明在开发环境和测试环境下激活此配置类,打包或者部署时候使用spring.profiles.active指明环境即可;

  3. 在配置文件中配置自定义的开关参数,并在SwaggerConfig配置类上添加@ConditionalOnProperty(name = "swagger.enable", havingValue = "true"),指明配置类的生效条件

    注:@ConditionalOnProperty 注解说明

    @ConditionalOnProperty注解能够控制某个@configuration修饰的配置类是否生效。具体操作是通过name和havingValue属性来实现,name对应application.properties(yml)中的某个属性值,如果该值为空,则返回false;如果值不为空,则将该值与havingValue指定的值进行比较,如果一样则返回true;否则返回false。如果返回值为false,则该configuration不生效;为true则生效。

/**
 * @author : heibaiying
 * @description :  Swagger 配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enable}")
    private boolean swaggerEnable;

    /***
     * 配置swagger
     * 开发和测试环境下可以开启swagger辅助进行调试,而生产环境下可以关闭或者进行相应的权限控制,防止接口信息泄露
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.heibaiying.springboot.controller"))
                .paths(PathSelectors.any())
                .paths(doFilteringRules())
                .build();
    }

    /***
     * 接口文档的描述信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("spring boot swagger2 用例")
                .description("描述")
                .licenseUrl("https://mit-license.org/")
                .version("1.0")
                .build();
    }

    /**
     * 可以使用正则定义url过滤规则
     */
    private Predicate<String> doFilteringRules() {
        return not(
                regex("/ignore/*")
        );
    }
}

application.properties :

#swagger启用开关
swagger.enable = true

2.3 swagger注解的使用和说明

@Slf4j
@Api(value = "产品接口", description = "产品信息接口")
@RestController
public class ProductController {

    /***
     * 一个标准的swagger注解
     */
    @ApiOperation(notes = "查询所有产品", value = "产品查询接口")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "id", value = "产品编号", paramType = "path", defaultValue = "1")
    )
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "无效的请求"),
            @ApiResponse(code = 401, message = "未经过授权认证"),
            @ApiResponse(code = 403, message = "已经过授权认证,但是没有该资源对应的访问权限"),
            @ApiResponse(code = 404, message = "服务器找不到给定的资源,商品不存在"),
            @ApiResponse(code = 500, message = "服务器错误")
    })
    @GetMapping(value = "/product/{id}", produces = "application/json")
    public ResponseEntity<Product> getProduct(@PathVariable long id) {
        Product product = new Product(id, "product" + id, new Date());
        return ResponseEntity.ok(product);
    }

    /***
     * 如果用实体类接收参数,则用实体类对应的属性名称指定参数
     */
    @ApiOperation(notes = "保存产品", value = "产品保存接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "产品编号", paramType = "body", defaultValue = "1"),
            @ApiImplicitParam(name = "name", value = "产品名称", paramType = "body"),
            @ApiImplicitParam(name = "date", value = "产品生产日期", paramType = "body")
    }
    )
    @PostMapping(value = "/product")
    public ResponseEntity<Void> saveProduct(@RequestBody Product product) {
        System.out.println(product);
        return ResponseEntity.ok().build();
    }

    /***
     * 在配置类中指明了该接口不被扫描到,可以在配置类中使用正则指定某一类符合规则的接口不被扫描到
     */
    @ApiOperation(notes = "该接口会被忽略", value = "产品保存接口")
    @PostMapping(value = "/ignore")
    public ResponseEntity<Product> ignore() {
        return ResponseEntity.ok().build();
    }

    /**
     * 不加上任何swagger相关的注解也会被扫描到 如果不希望被扫描到,需要用 @ApiIgnore 修饰
     */
    @PostMapping(value = "/normal")
    public ResponseEntity<Void> normal() {
        return ResponseEntity.ok().build();
    }

    @ApiIgnore
    @PostMapping(value = "/apiIgnore")
    public ResponseEntity<Void> apiIgnore() {
        return ResponseEntity.ok().build();
    }
}

swagger 为了最大程度防止对逻辑代码的侵入,基本都是依靠注解来完成文档描述。常用注解如下:

Annotation Attribute Target Property Description
RequestHeader defaultValue Parameter#defaultValue e.g. @RequestHeader(defaultValue="${param1.defaultValue}")
ApiModelProperty value ModelProperty#description e.g. @ApiModelProperty(value="${property1.description}")
ApiModelProperty description ModelProperty#description e.g. @ApiModelProperty(notes="${property1.description}")
ApiParam value Parameter#description e.g. @ApiParam(value="${param1.description}")
ApiImplicitParam value Parameter#description e.g. @ApiImplicitParam(value="${param1.description}")
ApiOperation notes Operation#notes e.g. @ApiOperation(notes="${operation1.description}")
ApiOperation summary Operation#summary e.g. @ApiOperation(value="${operation1.summary}")
RequestParam defaultValue Parameter#defaultValue e.g. @RequestParam(defaultValue="${param1.defaultValue}")
  1. @Api:Api 用在类上,说明该类的作用;

  2. @ApiOperation:用在方法上,说明方法的作用;

  3. @ApiParam:用在参数上,说明参数的作用;

  4. @ApiImplicitParams:用在方法上说明方法参数的作用;

  5. @ApiImplicitParam:用在@ApiImplicitParams注解中,描述每个具体参数;

  6. @ApiResponses:一组@ApiResponse的配置;

  7. @ApiResponse:请求返回的配置;

  8. @ResponseHeader:响应头的配置;

  9. @ApiModel:描述一个Model的信息(一般用在post创建的时候,使用@RequestBody接收参数的场景);

  10. @ApiModelProperty:描述model的属性。

  11. @ApiIgnore:可以用于类、方法、属性,代表该方法、类、属性不被swagger的文档所管理。

2.4 swagger-ui 可视化接口文档

接口文档访问地址:http://localhost:8080/swagger-ui.html ,文档主界面如下:

2.5 利用swagger-ui进行接口测试

​点击对应接口的try it out按钮可以进行接口测试,此时可以输入对应的参数的值,然后点击下方的Execute按钮发送请求。

post方法可以直接修改model 对应的 json数据 ,然后点击下方的Execute按钮发送请求。

附:源码Gitub地址:https://github.com/heibaiying/spring-samples-for-all

spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档的更多相关文章

  1. spring boot / cloud (三) 集成springfox-swagger2构建在线API文档

    spring boot / cloud (三) 集成springfox-swagger2构建在线API文档 前言 不能同步更新API文档会有什么问题? 理想情况下,为所开发的服务编写接口文档,能提高与 ...

  2. Spring Boot 系列(七)Swagger2-生成RESTful接口文档

    Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服 ...

  3. Spring Boot(九)Swagger2自动生成接口文档和Mock模拟数据

    一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...

  4. Spring Boot Swagger2自动生成接口文档

    一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 1.问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 2 ...

  5. Spring Boot 集成Swagger2生成RESTful API文档

    Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...

  6. springboot集成swagger2构建RESTful API文档

    在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...

  7. springcloud集成swaggerui做动态接口文档

    1.配置文件pom,一定要使用2.4以上的,2.4默认请求方式是json,会导致getmapping设置参数类型对对象时,swaggerui界面不能指定为其他类型,反正就是各种坑,不建议用 <d ...

  8. Spring Boot 集成 Swagger,生成接口文档就这么简单!

    之前的文章介绍了<推荐一款接口 API 设计神器!>,今天栈长给大家介绍下如何与优秀的 Spring Boot 框架进行集成,简直不能太简单. 你所需具备的基础 告诉你,Spring Bo ...

  9. Spring Boot2配置Swagger2生成API接口文档

    一.Swagger2介绍 前后端分离开发模式中,api文档是最好的沟通方式. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务. 及时性 (接 ...

随机推荐

  1. ADO.net Connection对象简介

    Connection对象 学习的是刘皓的文章  ADO.NET入门教程(四) 品味Connection对象 这篇文章开始水平一般起来了,主要介绍了要优雅的使用这个对象 1 用try...catch.. ...

  2. codeforces Round #259(div2) D解决报告

    D. Little Pony and Harmony Chest time limit per test 4 seconds memory limit per test 256 megabytes i ...

  3. 回调函数实现类似QT中信号机制

    1. 定义回调接口类: class UIcallBack { public: virtual void onAppActivated() = 0; virtual void onShowMore()  ...

  4. otrs离线部署

    OTRS5离线部署 参考地址:https://doc.otrs.org.cn/doc/manual/admin/stable/zh_CN/html/manual-installation-of-otr ...

  5. WPF 左键单击弹出菜单 ContextMenu

    原文:WPF 左键单击弹出菜单 ContextMenu WPF中的ContextMenu在XAML中可直接做出来,但是仅限于右键弹出菜单,如果需要添加左键弹出功能,只需要在事件中添加Click事件 X ...

  6. fzu-1753 Another Easy Problem-高速求N!多少个月p

    它计算每个C(N,M)什么号码乘以像.... #include <iostream> #include<stdio.h> #include<vector> #inc ...

  7. Tab切换效果的实现

    <!--引用jquery和bootstrap--> <link rel="stylesheet" href="~/Content/bootstrap.m ...

  8. 反编译 war 包成传统项目的方法

    需求 项目老大让外包做了官网,不甚满意,想自己搞搞,遂叫我反编译他们发过来的 war 包. 方法 第一步:解压 war 包其实就是 zip 压缩包,用 zip 解压. 第二步:反编译 查看 war 包 ...

  9. UNITY VR 视频/图片 开发心得(二)

    上回说到了普通的全景图片,这回讲真正的VR. 由于这种图片分为两部分,所以我们需要两个Camera对象以及两个球体.首先新建一个Camera对象,并将其命名为RightEye(其它名字也无妨,只要你自 ...

  10. C# GC Finalizer IDispseable,.Net的垃圾回收机制

    1.GC只能回收堆里的托管资源 2.GC 回收,"代"的概念 .net 托管资源分三代,代数越大 资源的生命周期越长. 0 代 和1代的资源比较少可以比较频率的回收, 回收2代以上 ...