如何在Ballerina中标记特定资源及生成带标签的Swagger文件？

为单个资源函数添加标签 #

当前Ballerina的OpenAPI工具链已弃用@openapi:resourceconfig，改为直接通过@openapi:Tags注解为特定资源函数标注专属标签，示例写法如下：

import ballerina/http;
import ballerina/openapi;

// 服务级标签：作为所有资源的默认标签
@openapi:Tags {
    tags: ["Core API"]
}
service /api on new http:Listener(8080) {
    // 为用户管理资源添加专属标签
    @openapi:Tags {
        tags: ["Users", "Management"]
    }
    resource function get users() returns http:Ok {
        return http:Ok { body: "User list retrieved" };
    }

    // 为产品目录资源添加不同标签
    @openapi:Tags {
        tags: ["Products", "Catalog"]
    }
    resource function get products() returns http:Ok {
        return http:Ok { body: "Product catalog retrieved" };
    }
}

排除服务级默认标签 #

如果某个资源不需要继承服务级的标签，可搭配@openapi:ExcludeTags注解移除指定的默认标签：

@openapi:Tags {
    tags: ["Core API"]
}
service /api on new http:Listener(8080) {
    @openapi:ExcludeTags {
        tags: ["Core API"]
    }
    @openapi:Tags {
        tags: ["Public Endpoint"]
    }
    resource function get public() returns http:Ok {
        return http:Ok { body: "Public content" };
    }
}

生成带标签的Swagger文件 #

使用Ballerina CLI的openapi generate命令即可生成包含资源级标签的Swagger文件：

bal openapi generate --input your_service_file.bal --output swagger_output.yaml

生成的Swagger文件中，每个资源的tags字段会精确对应你在函数上标注的标签集合。

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