文档章节

RESTful API 利器 Swagger

leihit1991
 leihit1991
发布于 2016/10/16 14:10
字数 1772
阅读 70
收藏 1

原文博客地址: http://www.razorer.com/2016/10/16/swagger-intro/

目前公司的项目对外交互都是采用 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的官方文档:https://springfox.github.io/springfox/docs/snapshot/.

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

引入 SpringFox-Swagger

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

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- Swagger -->
<!--springfox的基本信息文档: http://springfox.github.io/springfox/docs/current/#architecture-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.0</version>
</dependency>

SpringBoot 支持 Swagger

  • 在Application启动类中支持Swagger,增加@EnableSwagger2注解, 让SpringBoot项目支持 Swagger
1
2
3
4
5
6
7
8
@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包括:
1
2
3
4
5
6
7
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的类的具体配置信息如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
@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运行结果

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

swagger ui

总结

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

相关参考

© 著作权归作者所有

leihit1991
粉丝 0
博文 1
码字总数 1772
作品 0
朝阳
私信 提问
加载中

评论(0)

用Swagger调用Harbor Registry的REST API

本文原作者为开源企业级容器Registry Harbor项目的工程师王锟,主要介绍如何使用Harbor内置Swagger来测试和调用Harbor的API。笔者做了少量修改。 Swagger简介 Swagger是最流行的RESTful API...

project_harbor
2016/04/21
1.5K
0
使用Swagger2构建Spring Boot RESTful AIP 文档

上一篇我们介绍了如何使用Spring Boot快速构建RESTful API “Spring Boot与RESTful API ” ,本篇则介绍一个配合Spring Boot快速构建RESTful文档的工具 由于Spring Boot具有快速开发、便捷部...

老虎是个蛋蛋
2016/12/23
1.9K
5
使用swagger 生成 Flask RESTful API

什么是 RESTful 什么是REST REST(英文:Representational State Transfer,又称具象状态传输)是Roy Thomas Fielding博士于2000年在他的博士论文 中提出来的一种万维网软件架构风格,目的是...

goodspeed
2017/07/11
0
0
Yii2+Swagger搭建RESTful风格的API项目

在现有的Advanced Template上搭建RESTful API项目的步骤: 本案例前提说明: 本例中不使用yiirestActiveController自动创建的API,而是自定义一个API 使用Auth2.0的Bearer模式进行身份验证 ...

无上@诀
2016/08/19
0
0
补习系列-springboot-restful应用

一、目标 了解 Restful 是什么,基本概念及风格; 能使用SpringBoot 实现一套基础的 Restful 风格接口; 利用Swagger 生成清晰的接口文档。 二、Restful 入门 什么是REST 摘自百科的定义:R...

美码师
2018/08/05
0
0

没有更多内容

加载失败,请刷新页面

加载更多

docker上启动nginx,并配置修改nginx的配置文件

1.使用docker 下载nginx 镜像 docker pull nginx 2.启动nginx docker run --name nginx -p 80:80 -d nginx 这样就简单的把nginx启动了,但是我们想要改变配置文件nginx.conf ,进入容器,命令...

yuxw
30分钟前
45
0
管道符|重定向与环境变量

重定向 管道符 通配符 转义符 环境变量 重定向 重定向(把命令和文件结合起来使用) 输入重定向< 将文件重定向到命令里,让文件去匹配命令执行,与正常的名命令对文件的执行方向相反,但结果一...

Venus7
32分钟前
32
0
恢复丢失的Joomla密码的最常用方法

忘记密码是很常见的事情。有些用户将密码保存在其默认浏览器内存中,几个月后您可能会忘记任何事情。我们中有些人甚至不记得他们在Joomla安装时发出的密码。本文介绍了如何重置Joomla管理员密...

六艺网络专注于Joomla
34分钟前
46
0
更改后如何重新加载.emacs?

如何才能使Emacs重新加载在.emacs更新的所有定义,而无需重新启动Emacs? #1楼 在您的初始化文件中定义它,并通过Mx reload-user-init-file调用 (defun reload-user-init-file() (interact...

javail
41分钟前
50
0
我眼中的分布式系统可观测性

作者:黄东旭,PingCAP 联合创始人兼 CTO 位于 M87 中心的特大质量黑洞示意图(© EHT Collaboration) 今天的文章我想从这张模糊的照片说起。 相信很多小伙伴对这张照片并不陌生,这是去年人...

TiDB
41分钟前
73
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部