CentOS Swagger如何与其他服务集成

在CentOS上集成Swagger与其他服务，这件事说起来其实没有想象中那么复杂。本质上就是三步走：装好Swagger、写好配置文件、然后把它挂到你的服务框架里。下面把具体路径拆开讲清楚。

先说第一种场景，以Python的Flask服务为例。

安装Swagger

这一步很简单，直接用pip搞定。但前提是CentOS上得先有Python3和pip。如果还没装，一条命令的事：

sudo yum install python3 python3-pip

然后安装Swagger相关的库：

pip3 install swagger-ui-express

创建Swagger配置文件

你需要一个YAML或JSON格式的文件来定义API规范。比如创建一个swagger.json，里面写上API的基本信息、路径和数据结构。下面是一个最小示例：

{
  "swagger": "2.0",
  "info": {
    "title": "Sample API",
    "description": "A sample API to demonstrate Swagger integration",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "List all users",
        "responses": {
          "200": {
            "description": "An array of users",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/User"
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "User": {
      "type": "object",
      "properties": {
        "id": { "type": "integer", "format": "int64" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"]
    }
  }
}

集成到Flask服务

用Flask + Flasgger的组合很常见。简单写个示例：

from flask import Flask, jsonify
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

@app.route('/users')
def get_users():
    users = [
        {'id': 1, 'name': 'Alice'},
        {'id': 2, 'name': 'Bob'}
    ]
    return jsonify(users)

if __name__ == '__main__':
    app.run(debug=True)

运行服务：

python3 app.py

然后打开浏览器，访问 http://<你的服务器IP>:5000/apidocs，就能看到Swagger UI界面，API文档自动生成，可以直接在上面测试接口。

其他服务的集成：以Spring Boot为例

如果你用的是Ja va生态，集成方式其实大同小异。以Spring Boot为例，Springfox是常用的选择。

首先在pom.xml里添加依赖：

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

然后创建一个配置类，告诉Swagger要扫描哪个包下的控制器：

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}

运行Spring Boot应用：

./mvnw spring-boot:run

访问 http://<你的服务器IP>:8080/swagger-ui.html，同样能看到清晰的API文档界面。

总结一下，无论是Python的Flask还是Ja va的Spring Boot，核心思路是一致的：安装Swagger依赖、配置API规范、把Swagger挂到服务启动入口上。剩下的工作，Swagger UI会自动替你完成文档生成和交互测试。在CentOS上跑这些服务，记得打开对应的防火墙端口就行。这样一套操作下来，API的可视化管理就变得相当方便了。