Swagger UI/Editor/Codegen实战

最新推荐文章于 2023-11-30 15:29:58 发布

weixin_34366546

最新推荐文章于 2023-11-30 15:29:58 发布

阅读量408

点赞数

文章标签： ui json python

原文链接：https://my.oschina.net/guol/blog/993689

版权

为什么80%的码农都做不了架构师？>>>

背景

最近部门在推进前后端分离，服务微服务化的演进，这两者之间有个共同点就是服务之间的调用都是通过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