如何为Ballerina API实现Swagger API规范并生成文档？

Ballerina原生支持OpenAPI（原Swagger）文档的生成与交互式访问，以下是具体操作步骤：

1. 给API添加元数据注解 #

要生成语义清晰的文档，需为服务、资源函数、参数及返回值添加OpenAPI专属注解，让工具识别API的业务语义：

示例服务代码 #

import ballerina/http;
import ballerina/openapi;

// 服务级元数据定义
@openapi:ServiceInfo(
    title = "用户管理API",
    version = "1.0.0",
    description = "用于管理用户基础信息的REST接口集合"
)
service /users on new http:Listener(8080) {

    // 获取所有用户列表的接口描述
    @http:GET
    @openapi:Operation(
        summary = "获取全部用户",
        description = "返回系统内所有已注册用户的基础信息"
    )
    @openapi:Response(
        statusCode = 200,
        description = "成功返回用户列表",
        content = {
            "application/json": {schema: "User[]"}
        }
    )
    resource function get []() returns User[]|error {
        return [{id: 1, name: "Alice"}, {id: 2, name: "Bob"}];
    }

    // 根据ID查询单个用户的接口描述
    @http:GET
    @openapi:Operation(
        summary = "按ID查询用户",
        description = "通过用户唯一ID获取其详细信息"
    )
    @openapi:Parameter(
        name = "userId",
        in = "path",
        description = "目标用户的ID",
        required = true
    )
    @openapi:Response(
        statusCode = 200,
        description = "成功返回用户详情",
        content = {
            "application/json": {schema: "User"}
        }
    )
    @openapi:Response(
        statusCode = 404,
        description = "未找到对应ID的用户"
    )
    resource function get [int userId]() returns User|http:NotFound|error {
        if userId == 1 {
            return {id: 1, name: "Alice", email: "alice@example.com"};
        }
        return http:NOT_FOUND;
    }
}

// 定义用户数据结构，工具会自动转换为OpenAPI Schema
type User record {
    int id;
    string name;
    string? email;
};

2. 生成静态OpenAPI文档文件 #

使用Ballerina CLI命令可直接导出标准的OpenAPI YAML/JSON文件，供其他开发者下载或导入到API管理工具中：

生成命令 #

# 针对单个服务文件生成YAML格式文档
bal openapi generate --mode service --input users_service.bal --output openapi.yaml

# 项目根目录执行，自动识别所有服务并生成JSON格式文档
bal openapi generate --output openapi.json

执行后会在指定路径生成包含完整API定义的静态文档文件。

3. 启用交互式Swagger UI访问 #

Ballerina HTTP服务支持自动暴露交互式Swagger UI，无需额外部署：

1. 确保服务已添加@openapi:ServiceInfo注解
2. 启动服务后，访问服务根路径下的/swagger端点，例如：

   http://localhost:8080/swagger
   

   页面会提供API的可视化预览，开发者可直接在页面上测试接口、查看参数与返回结构。

注意事项 #

• Ballerina生成的是OpenAPI 3.x版本文档，完全兼容Swagger工具链
• 数据类型（如示例中的User record）定义越清晰，自动生成的Schema越准确
• 如需自定义安全方案、标签等细节，可扩展使用openapi模块的其他注解

内容的提问来源于stack exchange，提问作者Poorna