Swagger UI/Editor/Codegen实战

原创
2017/06/20 14:43
阅读数 1W

背景

        最近部门在推进前后端分离,服务微服务化的演进,这两者之间有个共同点就是服务之间的调用都是通过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文件的编写,下面两篇文章就够了:

        Swagger从入门到精通

        Swagger Specification

   

 

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部