利用 Swagger Kubernetes 调试 Kubernetes 的 Spring 应用 API & 生成 API 文档
文章目录
!版权声明：本博客内容均为原创,每篇博文作为知识积累,写博不易,转载请注明出处。
系统环境：
- Kubernetes 版本：1.20.3
- Swagger Kubernetes 版本： v1.1.1
- Swagger Kubernetes Github 地址: https://github.com/my-dlq/swagger-kubernetes
一、简介
Swagger Kubernetes 是能够将 Kubernetes 环境下 Spring 项目的 Swagger 文档聚合，只要 Spring 项目中引用了 Swagger 工具暴露 Swagger API，就可以将其所有的这类项目 Swagger 接口聚合到 Swagger Kubernetes 项目当中。
Swagger Kubernetes 是拥有在 Kubernetes 环境中服务发现功能，能够自动服务发现那些暴露 Swagger API 的服务，然后生成 Markdown 格式的文档展示在页面上，通过反向代理可以直接调用对应服务接口进行调试工作。
由于方便，已经将该项目以 Docker 镜像的方式存放到 Docker Hub 仓库。
- hub地址：https://hub.docker.com/r/mydlqclub/swagger-kubernetes
- Docker镜像： mydlqclub/swagger-kubernetes
“说白就是监控 Kubernetes 环境下引入 Swagger2 组件的 SpringBoot 应用，会自动服务发现，不需要额外的注册中心。”
二、架构图
三、如何使用
Swagger Kubernetes 是应用在 Kubernetes 环境下，监控服务所在 Namespace 的各个 Spring 应用 Swagger API 接口，所以需要将此应用部署到 Kubernetes 环境下。
下面将演示如何在 Kubernetes 集群部署 Swagger Kubernetes。
1、创建 ServiceAccount
swagger-kubernetes-ac.yaml
请提前修改里面的 Namespace
1apiVersion: v1
2kind: ServiceAccount
3metadata:
4 name: swagger-kubernetes
5 namespace: mydlqcloud
6---
7kind: Role
8apiVersion: rbac.authorization.k8s.io/v1beta1
9metadata:
10 name: swagger-kubernetes-role
11 namespace: mydlqcloud
12rules:
13 - apiGroups: [""]
14 resources: ["services","endpoints"]
15 verbs: ["get","list","watch"]
16---
17kind: RoleBinding
18apiVersion: rbac.authorization.k8s.io/v1
19metadata:
20 name: rbac-role-binding
21 namespace: mydlqcloud
22subjects:
23 - kind: ServiceAccount
24 name: swagger-kubernetes
25 namespace: mydlqcloud
26roleRef:
27 apiGroup: rbac.authorization.k8s.io
28 kind: Role
29 name: swagger-kubernetes-role
创建 ServiceAccount
1$ kubectl apply -f swagger-kubernetes-ac.yaml
2、创建 Swagger kubernetes 服务
swagger-kubernetes-deploy.yaml
1apiVersion: v1
2kind: Service
3metadata:
4 name: swagger-kubernetes
5 namespace: mydlqcloud
6 labels:
7 app: swagger-kubernetes
8spec:
9 ports:
10 - name: tcp
11 port: 8080
12 nodePort: 32255
13 targetPort: 8080
14 type: NodePort
15 selector:
16 app: swagger-kubernetes
17---
18apiVersion: apps/v1
19kind: Deployment
20metadata:
21 name: swagger-kubernetes
22 namespace: mydlqcloud
23 labels:
24 app: swagger-kubernetes
25spec:
26 selector:
27 matchLabels:
28 app: swagger-kubernetes
29 template:
30 metadata:
31 labels:
32 app: swagger-kubernetes
33 spec:
34 serviceAccountName: swagger-kubernetes #这里引用创建的服务账户，否则可能没有读取服务所在 Namespace 的权限
35 containers:
36 - name: swagger-kubernetes
37 image: mydlqclub/swagger-kubernetes:latest
38 #国内使用 aliyun 镜像仓库
39 #image: registry.cn-beijing.aliyuncs.com/mydlq/swagger-kubernetes:latest
40 imagePullPolicy: IfNotPresent
41 ports:
42 - name: server
43 containerPort: 8080
44 resources:
45 limits:
46 cpu: 2000m
47 memory: 512Mi
48 requests:
49 cpu: 500m
50 memory: 512Mi
创建 ServiceAccount
-n：指定启动的 namespace，执行前请先修改此值
1$ kubectl apply -f swagger-kubernetes-deploy.yaml -n mydlqcloud
3、查看创建的资源
1$ kubectl get pod,service -n mydlqcloud | grep swagger-kubernetes
2
3pod/swagger-kubernetes-5577dc9d8d-6sz4f 1/1 Running 0
4service/swagger-kubernetes NodePort 10.10.204.142 <none> 8080:32255/TCP
4、访问 Swagger Kubernetes
输入地址： http://Kubernetes集群地址:32255 访问 Swagger Kubernetes
四、可配置环境变量参数
一般情况用默认配置即可，有些特殊情况需要自定义设置，可以做如下配置：
| 变量名 | 默认值 | 描述 |
|---|---|---|
| KUBERNETES_CONNECT_URL | https://kubernetes.default.svc.cluster.local | Kubernetes API 地址 |
| KUBERNETES_CONNECT_TOKEN | Service Pod ServiceAccount 所拥有的权限 | KUBERNETES_CONNECT_TOKEN |
| DISCOVERY_NAMESPACE | Service 所在的 Namespace | Swagger 聚合文档的 Kubernetes Namespace |
| DISCOVERY_INITIAL_INTERVAL | 60 | 服务发现的更新间隔，推荐60秒 |
| SWGGER_API_PATH | /v2/api-docs | 应用 Swagger API 地址 |
| IGNORE_SERVICES | - | 默认的忽略列表，例如设置为"service1,service2,......" |
| ACTUATOR_PORT | 8080 | SpringBoot management 端口设置 |
| ACTUATOR_TYPE | * | SpringBoot Actuator 暴露的参数，可以设置为 health,info,env,metrics,prometheus.... |
!版权声明：本博客内容均为原创,每篇博文作为知识积累,写博不易,转载请注明出处。