企业级开源系统-7：系统集成API管理工具Swagger

作者：私语茶馆

1.前言

        随着企业产品要有竞争力，越来越需要和周边系统集成，形成一个整体产业生态。例如IT领域企业公众号开发需要和微信集成，导航软件需要和地图系统集成，CT领域东数西算需要各种eTom子系统包括BSS/OSS/故障管理系统等集成，这些都需要定义和管理集成接口。随着接口的数量规模越来越大，版本升级和管理也相当复杂，一个工具协助大家实现API设计、文档生成、版本管理、在线集成测试等，这里比较推荐的是Swagger软件，同时支持IT领域的restful和CT领域的yang接口。本文详细介绍Swagger以及yang和swagger的集成。

2.Swagger介绍

       Swagger 是一个开源API设计和文档管理工具，同时可以提供在线测试API能力，生成交互式API文档，客户端SDK，服务端Stub，可以方便用户管理北向接口集成。

        常用Swagger管理的接口包括Restful接口，同时Swagger还提供Pyang语言的插件，可以用来管理CT（通信领域）的接口。Yang（Yet Another Next Generation）：是一个数据建模语言，用来定义网络管理的接口，这些接口运行在NETCONF或者RESTCONF协议。Yang也可以编译为Yaml（Yaml Ain't Markup language）语言，和Restfult接口互转。

2.1. Swagger的产品架构

        Swagger包括以下几个部件：

• SwaggerHub：是将所有产品进程到一个Integrated Platform，以便于快速构建稳定和API
• Swagger UI：提供了一个HTML/Jscript/Css集合，可以动态产生文档和测试沙箱

Swagger UI提供了一个HTML/Jscript/Css集合，可以动态产生文档和测试沙箱。

Swagger UI无依存关系，可以安装在任何服务环境里面。

• Swagger Editor：基于浏览器的编辑器，可以用Yaml或者Json格式。
• Swagger Codegen：命令行工具，用于生成客户端和服务端的Stub代码。
• Swagger Core：基于Java的libraries，用生成和查看Swagger定义。
• Swagger Specification：定义了如何描述一个API接口，所有Swagger产品基于这套规范。

3. 安装

3.1.实验环境

测试版本为：

       Unix版本 Python3.5.1， Pyang1.5， Pyang Swagger Plugin

       Windows版本：Python3.4.4 Pyang1.6 Pyang Swagger Plugin

安装路径：

       PythonHome=/root/yangtools/Python-3.5.1

       PyangHome=/root/yangtools/pyang-1.5

其他要求：

Java 7

Apache maven 3.0.3 or greater

3.2.步骤

1. 下载https://github.com/swagger-api/swagger-ui/releases,版本号：Swagger UI2.1.4。

解压缩后，预编译的程序在‘dist’目录。

1. 下载Tomcat：

1. 虚拟根目录（WebApps）目录下增加Swagger目录，将Swagger的Json拷贝到Swagger目录下；
2. 修改D:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\web.xml下配置，将listings改为true，以便查看目录。

<servlet>

        <servlet-name>default</servlet-name>        <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>