使用 swagger-ui 可视化 Kubernetes API 文档

Posted 2021-10-28 写代码的明哥

在工作中，你可能需要基于 Kubernetes 提供的 API 进行开发，比如开发适合自己的控制台，Kubernetes 官方提供的 API 文档，有两个问题：

1. 非常的不直观，这个问题其实还好，自己克服一下也不是大问题
2. 只有 K8S api-server 的接口，这个就难办了，假如有新的 CRD 资源，比如 kubevirt ，又要去找 kubevirt 的 api 文档，关键是找不着

今天明哥给大家介绍一个工具，可以帮你解决这个问题。

这个工具叫 swagger-ui，可以把 k8s 暴露的 http 接口文档以 UI 界面呈现给你，你甚至还可以在上面进行调试，生成 curl 的请求命令。

1. 如何部署 swagger-ui

打开两个 ssh 连接到你的 K8S 集群中。

进入第一个窗口，执行如下命令建立一个反向代理

kubectl proxy --port=8080

进入第二个窗口，执行如下命令建立获取 k8s的 api 文档信息，输出到一个 k8s-swagger.json 文件中

curl localhost:8080/openapi/v2 > k8s-swagger.json

获取到后，第一个窗口就可以关闭了。

然后任选一个窗口，执行如下命令运行一个容器

docker run \\
    --rm \\
    -d \\
    -p 80:8080 \\
    -e SWAGGER_JSON=/k8s-swagger.json \\
    -v $(pwd)/k8s-swagger.json:/k8s-swagger.json \\
    swaggerapi/swagger-ui

2. 使用 swagger-ui

此时，你在浏览器上输入 http://ip 就可以看到一个经过可视化的 api 文档界面，其中包括安装在集群上的所有自定义资源的模型和路径！

里面的 api 非常多，你用得上的，用不上的，这里都有。
不仅有 api-server 的 API ，​其他所有你另外安装的 CRD 资源也都有。

比如我自己安装的 VirtualMachineInstance 资源，根据关键字，立马就找到 KubeVirt 创建虚拟机的 API

点击上面的 Try it out 可以修改请求体的参数，请生成一个 curl 命令，方便你进行调试。

---

文章最后给大家介绍三个我自己写的在线文档：

第一个文档：PyCharm 中文指南 1.0 文档

花了两个多月的时间，整理了 100 个 PyCharm 的使用技巧，为了让新手能够直接上手，我花了很多的时间录制了上百张 GIF 动图，有兴趣的前往在线文档阅读。

第二个文档：PyCharm 黑魔法指南 1.0 文档

系统收录各种 Python 冷门知识，Python Shell 的多样玩法，令人疯狂的 Python 炫技操作，Python 的超详细进阶知识解读，非常实用的 Python 开发技巧等。

第三个文档：Python 中文指南 1.0 文档

花了三个月时间写的一本 适合零基础入门 Python 的全中文教程，搭配大量的代码案例，让初学者对 代码的运作效果有一个直观感受，教程既有深度又有广度，每篇文章都会标内容的难度，是基础还是进阶的，可供读者进行选择，是一本难得的 Python 中文电子教程。

Swagger-UI的配置与使用

Swagger-UI 的官方地址：

http://swagger.wordnik.com

Github上的项目地址：

https://github.com/wordnik/swagger-ui

官方提供的demo地址

http://petstore.swagger.wordnik.com/

 

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger的目标是对REST API定义一个标准的和语言无关的接口，可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过Swagger进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger消除了调用服务时可能会有的猜测。

Swagger是一组开源项目，其中主要要项目如下：

Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

Swagger-js: 用于JavaScript的Swagger实现。

Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

 

由于公司项目为ci框架，直接在代码中通过ci的一个插件，实现注释生成文档的功能，具体为http://ym1623.github.io/codeigniter_apidoc/，所以此处不在用swagger-ui的文档生成功能，主要使用其api测试功能。

首先，在github中下载swagger-ui

在服务器中打开其dist

此页面中，通过调用json，然后实现了其具体文档测试。

可以通过http://www.sosoapi.com/，此平台，生成swaggerui中所需要的json格式文件