Linux中Swagger与Kubernetes如何结合使用

Linux环境下Swagger与Kubernetes结合使用的实践指南

在Linux系统中，Swagger（OpenAPI规范的可视化工具）与Kubernetes的结合主要围绕Kubernetes API文档的可视化和集群内自定义API的服务化展开。以下是具体实现步骤及注意事项：

一、Kubernetes API文档的可视化（快速查看集群原生API）

若需快速查看Kubernetes集群的原生API（如Pod、Deployment等资源），可通过以下步骤将集群API文档暴露给Swagger UI：

1. 启动Kubernetes API反向代理

使用kubectl proxy命令在本地启动一个反向代理，将Kubernetes API服务器的安全端点映射到本地端口（默认8080）。此步骤无需集群认证（仅适用于本地开发环境）：

kubectl proxy --port=8080

2. 获取集群OpenAPI文档

通过curl命令从代理地址获取Kubernetes集群的OpenAPI规范（openapi/v2版本），并保存为本地JSON文件：

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

该文件包含了Kubernetes集群所有原生资源的API定义（如路径、参数、响应结构等）。

3. 部署Swagger UI容器

使用Docker运行Swagger UI容器，将本地生成的k8s-swagger.json文件挂载到容器中，并暴露80端口供浏览器访问：

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

• -e SWAGGER_JSON：指定Swagger UI加载的API文档路径；
• -v：将本地JSON文件挂载到容器内的对应路径。

4. 访问Swagger UI界面

在浏览器中输入http://localhost，即可看到Kubernetes集群的所有原生资源及API操作（如GET /api/v1/pods、POST /apis/apps/v1/deployments等）。通过界面可直接发送请求，调试集群资源。

二、自定义API的服务化部署（Swagger UI整合业务API）

若需将业务系统的API（如Spring Boot、Node.js等应用）部署到Kubernetes，并通过Swagger UI统一管理，需完成以下步骤：

1. 编写OpenAPI规范文件

使用Swagger Editor或代码生成工具（如swagger-codegen）编写API规范文件（swagger.yaml或swagger.json），定义API的路径、参数、响应结构及组件（如数据模型）。示例如下：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
servers:
  - url: http://localhost:8000  # 业务API的实际地址
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

2. 部署业务API到Kubernetes

将业务应用打包为Docker镜像（如simple-api），并通过Kubernetes的Deployment和Service资源部署到集群：

• Deployment配置（deployment.yaml）：定义应用副本数、容器镜像及端口：

  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: simple-api-deployment
  spec:
    replicas: 3
    selector:
      matchLabels:
        app: simple-api
    template:
      metadata:
        labels:
          app: simple-api
      spec:
        containers:
        - name: simple-api
          image: simple-api:latest  # 替换为实际镜像
          ports:
          - containerPort: 3000     # 应用监听端口
  

• Service配置（service.yaml）：将集群内部流量导向业务Pod：

  apiVersion: v1
  kind: Service
  metadata:
    name: simple-api-service
  spec:
    selector:
      app: simple-api
    ports:
    - protocol: TCP
      port: 80
      targetPort: 3000  # 对应容器端口
    type: ClusterIP     # 集群内部访问
  

执行以下命令部署：

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

3. 部署Swagger UI到Kubernetes

通过Deployment和Service资源将Swagger UI部署到集群，使其能够访问业务API的OpenAPI规范：

• Deployment配置（swagger-ui-deployment.yaml）：使用官方Swagger UI镜像：

  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: swagger-ui
  spec:
    replicas: 1
    selector:
      matchLabels:
        app: swagger-ui
    template:
      metadata:
        labels:
          app: swagger-ui
      spec:
        containers:
        - name: swagger-ui
          image: swaggerapi/swagger-ui:latest
          ports:
          - containerPort: 8080
          env:
          - name: SWAGGER_JSON  # 指向业务API的OpenAPI规范地址
            value: "/app/swagger.yaml"
          volumeMounts:
          - name: swagger-volume
            mountPath: "/app"
        volumes:
        - name: swagger-volume
          configMap:
            name: swagger-config
  

• ConfigMap配置（swagger-config.yaml）：将swagger.yaml文件挂载为ConfigMap：

  kubectl create configmap swagger-config --from-file=swagger.yaml
  

• Service配置（swagger-ui-service.yaml）：暴露Swagger UI服务（可选择NodePort或Ingress）：

  apiVersion: v1
  kind: Service
  metadata:
    name: swagger-ui
  spec:
    selector:
      app: swagger-ui
    ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
    type: NodePort  # 或Ingress（推荐）
  

执行以下命令部署：

kubectl apply -f swagger-ui-deployment.yaml
kubectl apply -f swagger-ui-service.yaml

4. 配置Ingress访问（可选，推荐）

若需通过域名访问Swagger UI，可创建Ingress资源（需集群已启用Ingress Controller，如Nginx）：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: swagger-ui-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: swagger.example.com  # 替换为实际域名
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: swagger-ui
            port:
              number: 80

执行以下命令部署：

kubectl apply -f swagger-ui-ingress.yaml

配置完成后，通过http://swagger.example.com即可访问Swagger UI界面，查看并调试业务API。

三、注意事项

1. 认证与授权：若Kubernetes集群启用了RBAC或认证（如TLS证书），需在kubectl proxy或Swagger UI配置中添加认证信息（如--token参数或Authorization头），避免未授权访问。
2. 自定义资源支持：若集群中有自定义资源定义（CRD），需确保OpenAPI文档包含CRD的路径和结构（可通过kubectl get crd获取CRD信息，并更新swagger.yaml）。
3. 实时更新：修改swagger.yaml后，需重新创建ConfigMap并重启Swagger UI Pod（kubectl rollout restart deployment/swagger-ui），确保文档同步。
4. 生产环境安全：生产环境中建议使用Ingress替代NodePort，并通过HTTPS加密流量（如使用Cert-Manager申请免费SSL证书）；同时限制Swagger UI的访问权限（如仅允许内部网络或特定用户）。

通过以上步骤，可在Linux环境中实现Swagger与Kubernetes的有效结合，既方便查看集群原生API，又能统一管理业务API的文档与调试。