"YANG, OpenAPI, Swagger"实操

因为要熟悉从YANG model到Swagger UI的过程，搜到这篇文章，然后就按部就班进行操作。
关于OpenAPI和Swagger的简介，可以看这里

前言

下面的操作演示了如何从一篇RFC文档通过各种开源工具直至生成Swagger的过程。RFC8299的题目是。是否懂得相关网络知识并不会影响下面的演示。

下面的操作是基于CentOS7.7系统进行的，需要先安装好需要的工具。

yum install git python-pip -y
easy_install --upgrade pip
pip install pyang
pip install --user --upgrade setuptools

通过网页浏览器可以看到看到最终的效果。

第一步

• 创建工作目录

[root@localhost ~]# mkdir yang_rfcs
[root@localhost ~]#  cd yang_rfcs/
[root@localhost yang_rfcs]# 

第二步

• 下载txt格式的rfc8299

[root@localhost yang_rfcs]# wget https://www.rfc-editor.org/rfc/rfc8299.txt

第三步

• 使用开源工具xym来从RFC文档中提取出YANG model的相关内容

[root@localhost yang_rfcs]# git clone https://github.com/xym-tool/xym.git
[root@localhost yang_rfcs]# cd xym/
[root@localhost xym]# 
[root@localhost xym]# python setup.py install
...
[root@localhost xym]# xym ../rfc8299.txt --dstdir ../

Extracting 'ietf-l3vpn-svc@2018-01-19.yang'
Created the following models:
ietf-l3vpn-svc@2018-01-19.yang
[root@localhost xym]# 
[root@localhost xym]# cd ../
[root@localhost yang_rfcs]# ll
total 412
-rw-r--r-- 1 root root  72828 4月  11 08:13 ietf-l3vpn-svc@2018-01-19.yang
-rw-r--r-- 1 root root 344738 1月  20 2018 rfc8299.txt
drwxr-xr-x 9 root root    242 4月  11 08:05 xym
[root@localhost yang_rfcs]# 
[root@localhost yang_rfcs]# mv ietf-l3vpn-svc@2018-01-19.yang ietf-l3vpn-svc.yang
[root@localhost yang_rfcs]# 
[root@localhost yang_rfcs]# ll
total 412
-rw-r--r-- 1 root root  72828 4月  11 08:13 ietf-l3vpn-svc.yang
-rw-r--r-- 1 root root 344738 1月  20 2018 rfc8299.txt
drwxr-xr-x 9 root root    242 4月  11 08:05 xym
[root@localhost yang_rfcs]# 

第四步

• 使用EAGLE from the OpenNetworkingFoundation将yang文件转为JSON
• 按照原文操作是不行的，因为相关的tool是在这个project的一个分支上，所以应该直接拉取对应的分支

[root@localhost yang_rfcs]# git clone -b ToolChain https://github.com/OpenNetworkingFoundation/EagleUmlCommon.git
Cloning into 'EagleUmlCommon'...
remote: Enumerating objects: 5702, done.
remote: Total 5702 (delta 0), reused 0 (delta 0), pack-reused 5702
Receiving objects: 100% (5702/5702), 34.90 MiB | 3.45 MiB/s, done.
Resolving deltas: 100% (2627/2627), done.
[root@localhost yang_rfcs]# 
[root@localhost yang_rfcs]# 
[root@localhost EagleUmlCommon]# cd YangJsonTools/
[root@localhost YangJsonTools]# 
[root@localhost YangJsonTools]# ll
total 60
drwxr-xr-x 2 root root    23 4月  11 08:36 export
-rw-r--r-- 1 root root 16512 4月  11 08:36 json_schema.py
-rw-r--r-- 1 root root  3635 4月  11 08:36 README.md
-rw-r--r-- 1 root root 34409 4月  11 08:36 swagger.py
[root@localhost YangJsonTools]# 

• 使用swagger.py这个工具进行转换，得到rfc8299.json这个OpenAPI JSON文件

[root@localhost YangJsonTools]# pyang --plugindir ./ -f swagger -p ../ -o export/rfc8299.json ../../ietf-l3vpn-svc.yang --generate-rpc=False
[root@localhost YangJsonTools]# 
[root@localhost YangJsonTools]# ll export/
total 1276
-rw-r--r-- 1 root root      42 4月  11 08:36 README.md
-rw-r--r-- 1 root root 1298758 4月  11 08:43 rfc8299.json
[root@localhost YangJsonTools]# 

[root@localhost export]# pwd
/root/yang_rfcs/EagleUmlCommon/YangJsonTools/export
[root@localhost export]# 
[root@localhost export]# export EXPORTS=`echo $PWD`
[root@localhost export]# 

第五步

• 运行swagger这个docker，立即获得swagger-ui的相关环境(给docker点赞)
• 同时将上一步生成的json文件进行关联

[root@localhost export]# docker run --name swagger -d -p 80:8080 -e BASE_URL=/swagger -e SWAGGER_JSON=/swaggerfiles/rfc8299.json -v $EXPORTS:/swaggerfiles swaggerapi/swagger-ui
Unable to find image 'swaggerapi/swagger-ui:latest' locally
latest: Pulling from swaggerapi/swagger-ui
4167d3e14976: Pull complete 
bb292c78f105: Pull complete 
06e2f99e39f6: Pull complete 
04b68d059149: Pull complete 
4835b8b58a75: Pull complete 
84c674289d42: Pull complete 
c76cef198b6e: Pull complete 
786449cea7ff: Pull complete 
Digest: sha256:296a52d58294d60936955c661023e80c18c64afd56e9da83a6b57283ed7cbe9b
Status: Downloaded newer image for swaggerapi/swagger-ui:latest
b79be97ac7a0b9a1caf6b3419418becd2a145f348ac4b4d0ab99de70be4f94b2
[root@localhost export]# 
[root@localhost export]# docker ps | grep swagger
b79be97ac7a0        swaggerapi/swagger-ui                    "sh /usr/share/nginx…"   About a minute ago   Up About a minute   80/tcp, 0.0.0.0:80->8080/tcp   swagger
[root@localhost export]# 

第六步

• 打开网址http://host-ip/swagger
  
• Web显示的相关项，可以对照JSON文件的相关段落

后续

上面只是生成了一个“空壳”，点击执行并不会有什么效果。后续需要添加相关的代码，实现对应的功能。原文中有举例，感兴趣的同学可以自己试试。