RESTful API 利器 Swagger

15,200 阅读5分钟
原文链接: www.razorer.com

目前公司的项目对外交互都是采用 http resful的协议进行通信,数据格式采用 JSON RESTFUl的风格, 这种组合比较轻量级, 基本抛弃过去的xml格式. 但是在互联网后台服务中,都是采用分布式系统, 会将一个大的项目拆分成多个小的子系统, 每个团队各负责一个部分, 这个时候, 如何定义各系统的之间的接口以及如何就接口进行展示和沟通, 往往是一个头疼的问题. 之前的项目开发中, 一直采用纯粹的文档的形式, 随着业务的变化, 维护文档的更新是一个非常耗时耗力的事情. 这段时间看到了一个开源项目 swagger, 提供了一种从项目代码中自动生成接口文档的功能, 可以保持和代码的同步变化, 非常强大. 其中与Spring整合版本是Spring-Fox的开源项目, 已经和Spring框架进行了非常好的整合. 本文将对Swagger进行简单的一个介绍和Demo的实现.

Swagger是什么

Swagger是一系列RESTful API 的工具, 通过 Swagger 你可以获得项目的一种交互式文档, 客户端SDK的自动生成等功能. 我们从 Swagger Github 的官方主页摘录:

The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

所以, 不需要阅读源码和文档, 就可以让程序员和机器能够发现和理解服务的接口.

Swagger提供的主要工具包括:

Swagger Core

Swagger-core 是 Swagger的Java 实现. 是整个swagger工具的核心实现. Swagger Core是使用Java编程实现的.

Swagger Codegen

提供了根据swagger的接口定义文件(yaml形式), 直接生产相应的代码, 以一种命令行工具的形式

Swagger Editro

通过Spring的 Swagger Editor, 使用yaml语言先定义简单的接口, 然后通过 Swagger-codergen 就可以自动生成 相应的 服务端 和 客户端的调用代码了. 具体的Swagger Editor的操作界面参考如下,swagger editor 截图

使用操作步骤:

  • 使用Yaml语言, 定义好API接口
  • 点击 generate server code, 选择你要的语言, 就可以下载自动生成的相关接口的初始化项目了
  • 点击 generate client code, 选择你要的语言, 就可以下载自动生成调用这个接口的 客户端代码了.

通过上面的功能, 我们发现, 项目初始化之后, 我们就可以通过swagger工具, 快速生成我们需要的初始化项目了, 大大加快了我们的项目开发进度. 这个比 springboot initialize 更加的方便.

Swagger UI

Swagger UI 可以将你的项目接口自动生产具有交互的html页面, 是一个前端页面的自动生成项目. Swagger UI的 demo: swagger ui demo. Swagger UI的界面示意图: swagger ui

还有其他一系列关于RESTful API的swagger工具, 具体的使用 可以参考相应的官方文档, 都是比较简单易懂的. 具体使用参考官方网站.

Demo - SpringBoot项目中使用Swagger

SpringFox是一个自动检测和生成Spring 运行时的API接口 , SpringFox完全支持Swagger工具, 只要在 Spring的项目中引入相应的SpringFox-Swagger包, 就可以使用swagger一系列工具了. 具体的使用方法可以参考SpringFox的官方文档:springfox.github.io/springfox/d….

下面我也将实现一个简单的SpringFox-Swagger的demo. 具体的Demo源代码已经上传到Github上: 地址: github.com/DanielHit/d…

引入 SpringFox-Swagger

首先, 在已经有的SpringBoot项目中引入 SpringFox-Swagger包 分别引入了 springfox-swagger-uispringfox-swagger2 两个包, 目前最新的版本是 2.6.0.




    io.springfox
    springfox-swagger-ui
    2.6.0
    
    io.springfox
    springfox-swagger2
    2.6.0
    

SpringBoot 支持 Swagger

  • 在Application启动类中支持Swagger,增加@EnableSwagger2注解, 让SpringBoot项目支持 Swagger
@SpringBootApplication
@EnableSwagger2
public class DemoSpringSwaggerApplication {
 public static void main(String[] args) {
        SpringApplication.run(DemoSpringSwaggerApplication.class, args);
    }
    }

配置Swagger信息

  • 配置Swagger 接下来, 我们需要对我们的Swagger进行配置, 我们需要在我们的SpingBoot项目中增加一个Bean. Docket 是具体的配置类, 既可以使用 xml 配置, 也支持注解配置, 这里我们使用注解配置. 具体的Docket的doc: Docket. 其中最终的一些展示信息, 需要设置 Docket的apiInfo, ApiInfo包括:
private final String version; // 接口版本号
private final String title;   // 接口大标题
private final String description; // 具体的描述
private final String termsOfServiceUrl; // 服务说明url
private final String license; // licence
private final String licenseUrl; // licnce url
private final Contact contact;  // 接口作者联系方式

具体的配置类如下

Controller内容

我们假定demo中开发了两个controller, 但是我们不希望将IgnoreController的接口信息暴露在自动生成的文档里面, 这时候我们可以在 这个controller上加一个注解 @SwaggerIgnore(PS: 这个注解是我们自己定义的), 在 SwaggerConfig增加一个配置, 通过注解忽略API.

SwaggerConfig的配置信息

apis(not(withClassAnnotation(SwaggerIgnore.class))) //SwaggerIngore的注解的controller将会被忽略

SwaggerConfig的类的具体配置信息如下:


@Configuration
public class SwaggerConfig {
    @Bean
    public Docket merchantStoreApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("internal-api")
                .genericModelSubstitutes(DeferredResult.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(true)
                .pathMapping("/")// base,最终调用接口后会和paths拼接在一起
                .select()
                .apis(not(withClassAnnotation(SwaggerIgnore.class))) //SwaggerIngore的注解的controller将会被忽略
                .paths(or(regex("/api/.*")))
                .build()
                .apiInapiInfo.(testApiInfo());
    }
    private ApiInfo testApiInfo() {
        ApiInfo apiInfo = new ApiInfo("标题文档",//大标题
                "文档的详细说",//小标题
                "0.1",//版本
                "NO terms of service",
                "razorer@razorer.com",//作者
                "The Apache License, Version 2.0",//链接显示文字
                "www.razorer.com"//网站链接
        );
        return apiInfo;
    }
    }
``` 
在 `IgnoreController`上增加注解 `SwaggerIgnore`.就可以了.
`IgnoreController` 的配置
```java
@RestController
@SwaggerIgnore      //swagger根据这个注解, 将会忽略这个controller的接口
@RequestMapping("/api/")
public class IgnoreController {
    @RequestMapping("/ignroe/controller")
    public UserModel ignoreUserModel() {
        return new UserModel("fuck", 23);
    }
    }

Demo运行结果

  • 运行项目
java -jar targe/demo-spring-swagger-0.0.1-SNAPSHOT.jar

swagger ui

总结

Swagger是一款非常强大的RESTful API管理工具, 同时与现有的Spring各种框架有一个非常顺畅的集成, 有个Swagger API的工具之后, 将大大简化微服务中API的管理, 减少各个团队之间对于文档的管理 和 团队的沟通成本.

相关参考