背景
最近部门在推进前后端分离,服务微服务化的演进,这两者之间有个共同点就是服务之间的调用都是通过RESTFul API来进行的,这样之前的单体应用划分成多个服务,服务之间的接口定义如何在各个团队之间快速的传播、查看、修改就是个问题了,这时候swagger出现了。
介绍
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger的目标是对REST API定义一个标准的和语言无关的接口,可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过Swagger进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。
Swagger工具可以满足下列需求:
Swagger可以生成一个交互性的API控制台,开发者可以用来快速学习API,同时也方便测试人员了解API。
Swagger支持OpenApi规范生成代码,生成的客户端和服务器端框架代码可以加速开发和测试速度。
Swagger文件可以用不同的编程语言的代码注释中自动生成。
Swagger文档可作为客户产品文档的一部分进行发布,可用于项目内部API审核,支持API自动生成同步的在线文档。
swagger项目
Swagger是一组开源项目,其中主要要项目如下:
Swagger-ui:这是一套 HTML/CSS/JS 框架用于解析遵守 Swagger spec 的 JSON 或 YML 文件,可以为Swagger兼容API动态生成文档。
Swagger-editor:这是在线编辑器,用于验证你的 YML/JSON 格式的内容是否违反Swagger spec 。Swagger spec提供了一个方法,使我们可以用指定的JSON或者YAML摘要来描述你的API。可让使用者在浏览器里以YAML格式编辑Swagger API规范并实时预览文档。可以生成有效的Swagger JSON描述,并用于所有Swagger工具中。
Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明,这个工具可以为不同的平台生成客户端 SDK(比如 Java、JavaScript、Python 等)。这些客户端代码帮助开发者在一个规范平台中整合 API ,并且提供了更多健壮的实现,可能包含了多尺度、线程,和其他重要的代码。
Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
Swagger-js: 用于JavaScript的Swagger实现。
安装Swagger-ui
swagger ui只是简单的HTML/CSS/JS文件,不需要其他依赖,下载到本地后,在下载目录的dist目录上启动web服务即可。
下载
cd /opt/programs
git clone https://github.com/swagger-api/swagger-ui.git
nginx配置
location / {
root /opt/programs/swagger-ui/dist;
index index.html index.htm;
}
修改配置
dist/index.html
const ui = SwaggerUIBundle(
#url改成你的json地址,可以是网络地址,也可以是本地地址,我改成了本地地址
url: "swagger.json",
dom_id: '#swagger-ui',
浏览器访问
安装Swagger-editor
swagger editor只是简单的HTML/CSS/JS文件,不需要其他依赖(官方说依赖nodejs,其实不需要,官方只是为了使用npm安装http服务),下载到本地后,在下载目录的dist目录上启动web服务即可。
下载
cd /opt/programs/
git clone https://github.com/swagger-api/swagger-editor.git
nginx配置
location / {
root /opt/programs/swagger-editor;
index index.html index.htm;
}
浏览器访问
安装Swagger-codegen
依赖
jdk7 或者 jdk8
maven3
下载
cd /opt/programs/
git clone https://github.com/swagger-api/swagger-codegen.git
编译
mvn clean package
查看帮助
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar help
生成代码
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i /opt/programs/swagger-ui/dist/swagger.json -l python -o /tmp/python_client
SDK代码结构
root@172.31.68.241:/tmp# tree -L 2 python_client/
python_client/
├── docs
│ ├── ApiResponse.md
│ ├── Category.md
│ ├── Order.md
│ ├── PetApi.md
│ ├── Pet.md
│ ├── StoreApi.md
│ ├── Tag.md
│ ├── UserApi.md
│ └── User.md
├── git_push.sh
├── README.md
├── requirements.txt
├── setup.py
├── swagger_client
│ ├── api_client.py
│ ├── apis
│ ├── configuration.py
│ ├── __init__.py
│ ├── models
│ └── rest.py
├── test
│ ├── __init__.py
│ ├── test_api_response.py
│ ├── test_category.py
│ ├── test_order.py
│ ├── test_pet_api.py
│ ├── test_pet.py
│ ├── test_store_api.py
│ ├── test_tag.py
│ ├── test_user_api.py
│ └── test_user.py
├── test-requirements.txt
└── tox.ini
5 directories, 29 files
swagger spec
你可以通过一个文本编辑器来编辑Swagger文件,或者你也可以从你的代码注释中自动生成,有许多的Swagger库可以用来整合不同的代码库,这些 Swagger 库可以解析注释并且生成跟之前手动生成相同的 Swagger 文件。要掌握spec文件的编写,下面两篇文章就够了: