51学通信

深度解析 3GPP TS 29.501：5 Documenting 5GC SBI APIs (API文档化：从设计图到施工蓝图)

22分钟阅读

深度解析 3GPP TS 29.501：5 Documenting 5GC SBI APIs (API文档化：从设计图到施工蓝图)

本文技术原理深度参考了3GPP TS 29.501 V18.7.0 (2024-12) Release 18规范中，关于“Chapter 5 Documenting 5GC SBI APIs”的核心章节。本文旨在指导读者如何将第4章中构思的宏伟设计蓝图，转化为一份精确、规范、机器可读的“施工详图”——OpenAPI 3.0规范文件。

在前面的系列文章中，我们跟随API设计师小王，为他的NIAF（网络智能分析功能）服务Nniaf_Analytics完成了顶层设计（第4章）。他已经确立了API的RESTful风格、版本策略、URI结构以及核心交互模式。设计图纸虽然清晰，但它还停留在概念和文档层面。现在，小王面临着最关键的一步：将这份设计图纸，翻译成一份全世界（尤其是机器）都能看懂的通用工程语言。

这门“通用工程语言”就是OpenAPI 3.0。而第5章，正是这部语言的“官方语法书和写作指南”。它不是在讨论“应该设计什么”，而是在规定“应该如何书写”。这一章的重要性在于，它直接决定了5G服务化架构（SBA）的基石——“基于API契约的自动化”——能否实现。

小王深吸一口气，他知道，接下来的工作将是细致而严谨的。他需要将AnalyticsJob资源的每一个字段、每一个端点的每一个参数，都按照第5章的规定，精确地“雕刻”到nniaf-analytics.yaml这个文件中。这份文件将成为NIAF服务对整个5G世界的“法律文书”，是代码生成、自动化测试、服务发现和网络编排的唯一依据。

1. 解读 5.1 Naming Conventions (命名约定) - 统一API的“书面语”

在开始书写YAML文件之前，小王必须首先掌握这门语言的“词法”。第5.1节为API文档中的每一个可命名元素（从API服务名到JSON中的一个小小属性）都制定了严格的命名法典，确保整个5G生态系统的API“书面语”高度统一。

1.1 病例约定 (Case Conventions) - 词语的“拼写规则”

规范原文引用 (Clause 5.1.1): The following case conventions for names and strings are used in the 5GC SBI service APIs.

  1. UPPER_WITH_UNDERSCORE
  2. lower_with_underscore
  3. UPPER-WITH-HYPHEN
  4. lower-with-hyphen
  5. UpperCamel
  6. lowerCamel

深度解析： 规范定义了六种大小写和分隔符的组合方式，并为不同类型的元素指定了必须使用的约定。这绝非无谓的“代码洁癖”，而是为了消除歧义，降低开发者的认知成本，并方便工具进行静态检查。

小王的设计思考： 小王在团队的编码规范中，将这些约定做成了强制要求，并给出了Nniaf_Analytics服务中的具体示例。

命名约定格式描述在 Nniaf_Analytics 服务中的应用场景和示例
UPPER_WITH_UNDERSCORE全大写，下划线分隔枚举值 (Enumeration values)。例如，JobStatus枚举的可能值：IN_PROGRESS, COMPLETED, FAILED。
lower_with_underscore全小写，下划线分隔规范中较少使用，通常用于特定场景的标识符。
UPPER-WITH-HYPHEN全大写，中划线分隔规范中较少使用。
lower-with-hyphen全小写，中划线分隔URI路径段常量 和 查询参数名。例如：/analytics-jobs, ?job-status=COMPLETED。
UpperCamel大驼峰式 (每个单词首字母大写)数据类型名 (Schema names)。例如，AnalyticsJob, UeMobilityInfo, CallbackSubscription。
lowerCamel小驼峰式 (首单词小写，后续单词首字母大写)JSON对象属性名 和 URI路径变量名。例如："jobId": "...", "creationTime": "...", /analytics-jobs/{jobId}。

1.2 API命名与URI约定 (Clause 5.1.2 & 5.1.3)

在掌握了单词的“拼写”后，小王开始学习如何构造“短语”和“句子”——即API名称和URI。

规范原文引用 (Clause 5.1.2 API Naming Conventions): An API shall take the name of the corresponding service (e.g. Nudm_SubscriberDataManagement). When used in URIs the name shall be converted to lower-with-hyphen and may use an abbreviated form (e.g. nudm-sdm).

深度解析： 这里定义了一个重要的转换规则：

  • 服务名 (Service Name)：通常是UpperCamel或带有下划线的形式，如Nniaf_Analytics。这个名字用于服务注册和发现。
  • API名 (apiName in URI)：在URI中使用时，必须转换为lower-with-hyphen的形式，并且可以使用官方定义的缩写。这使得URI更加简洁、URL友好。

对于URI的路径和查询部分，规范也给出了详细的规则：

  • 路径段常量 (Path Segments)：用lower-with-hyphen，且代表资源集合的路径段应为复数（e.g., /analytics-jobs）。
  • 路径段变量 (Path Variables)：用lowerCamel并用{}包裹（e.g., /{jobId}）。
  • 自定义操作 (Custom Operations)：路径的最后一段应为一个动词（e.g., /terminate-all）。
  • 查询参数 (Query Parameters)：参数名用lower-with-hyphen（e.g., ?nf-type=AMF）。

小王的设计思考：

  • 他的服务名是 Nniaf_Analytics。
  • 在API URI中，apiName部分就是 nniaf-analytics。
  • 一个完整的Resource URI设计如下，完美遵循了所有命名约定： {apiRoot}/nniaf-analytics/v1/analytics-jobs/{jobId}/report?format=full

1.3 数据结构命名约定 (Clause 5.1.4)

最后，是关于API“说话”内容的约定——JSON对象内部的命名规则。

规范原文引用 (Clause 5.1.4): a) Names of attributes shall be represented using lowerCamel. b) Names of arrays … shall be plural rather than singular.

小王的设计思考： 他设计的AnalyticsJob数据模型的YAML片段，严格遵循了这些规则：

AnalyticsJob:
  type: object
  properties:
    jobId:          # lowerCamel
      type: string
    relatedUeIds:   # lowerCamel 且 plural (复数)
      type: array
      items:
        type: string
    status:
      $ref: '#/components/schemas/JobStatus' # UpperCamel for Schema ref

2. 解读 5.2 API Definition - 绘制API的“解剖图”

掌握了命名法典后，小王开始进入核心绘图工作。第5.2节提供了一套标准的“图纸模板”（以表格形式呈现），指导他如何一步步地、结构化地描述API的每一个细节。这些表格是规范正文的核心，也是最终生成OpenAPI YAML文件的直接输入。

2.1 资源结构与概览 (Clause 5.2.1)

首先，需要一张宏观的“鸟瞰图”，展示API的所有资源及其层级关系。

规范原文通过 “Figure 5.2.1-1: Resource URI structure of the API” 这个树状图，清晰地展示了如何可视化API的资源树。

深度解析： 这个图用不同样式的框来区分不同类型的资源节点：

  • 实线框: 普通资源（Document, Collection, Store）。
  • 虚线框: 自定义操作。
  • 无框: 纯粹的路径段，本身不是一个可操作的资源。

小王的设计思考： 小王为他的Nniaf_Analytics服务绘制了类似的资源树，并将其转化为规范中的**“Table 5.2.1-1: Resources and methods overview”**。

资源用途/名称资源URI (相对路径)HTTP方法/自定义操作服务操作描述
Analytics Jobs/analytics-jobsGET查询分析任务集合
POST创建一个新的分析任务
Individual Analytics Job/analytics-jobs/{jobId}GET读取指定的分析任务
PATCH修改指定的分析任务
DELETE删除指定的分析任务
Job Cancellation/analytics-jobs/{jobId}/cancelPOST (cancel)取消一个正在进行的分析任务

这张概览表让任何人都能在30秒内了解Nniaf_Analytics服务的核心能力。

2.2 资源与方法的精细解剖 (Clause 5.2.2)

接下来，是对上表中每一行进行“细胞级”的精细描述。规范为此定义了一系列标准表格模板。

小王的设计思考（以POST /analytics-jobs为例）： 小王需要为这个操作填写以下几张“标准体检表”。

1. 资源URI变量表 (类似 Table 5.2.2-1): 这个操作的URI是/analytics-jobs，不包含变量，所以此表为空。但对于/analytics-jobs/{jobId}，就需要填写：

名称定义
jobId代表一个分析任务的唯一标识符。

2. URI查询参数表 (类似 Table 5.2.2-2): POST /analytics-jobs 通常不使用查询参数，此表为空。

3. 请求体支持的数据结构表 (类似 Table 5.2.2-3):

数据类型存在性(P)基数(Cardinality)描述
AnalyticsJobCreateDataM (Mandatory)1包含创建一个新分析任务所需的所有信息。

4. 响应体支持的数据结构表 (类似 Table 5.2.2-4):

数据类型存在性(P)基数(Cardinality)响应码描述
AnalyticsJobM1201 Created任务创建成功。响应体中包含已创建任务的完整表示。
ProblemDetailsM1400 Bad Request请求格式错误或包含无效参数。
ProblemDetailsM1503 Service UnavailableNIAF服务当前过载，无法处理新任务。

通过填写这一系列标准化的表格，小王确保了对API每个细节的描述都是无歧义的、结构化的，为下一步生成YAML文件打下了坚实的基础。

3. 解读 5.3 OpenAPI specification files - 精雕细琢的“YAML艺术品”

万事俱备，只欠东风。现在，小王要将前面所有的设计原则、命名约定和表格化描述，最终物化为一份nniaf-analytics.yaml文件。第5.3节就是这份文件的“写作手册”。

规范原文引用 (Clause 5.3.1 General): 5GC SBI APIs’ OpenAPI specification files shall comply with the OpenAPI specification and with the present clause 5.3.

3.1 文件的“身份信息” (info, externalDocs, servers)

一份好的YAML文件，首先要有清晰的“自我介绍”。

规范原文引用 (Clause 5.3.3 Info): The OpenAPI specification file of an API shall contain an “info” object with the title that should be set to the same value as chosen for the API name … and with the version set as described in clause 4.3.

小王的设计思考（YAML片段）：

openapi: 3.0.0
 
info:
  title: Nniaf_Analytics
  version: 1.0.0
  description: |
    API for Network Intelligence Analytics Function Services.
    © 2024, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.
 
externalDocs:
  description: 3GPP TS 29.xyz V18.7.0; 5G System; NIAF Services.
  url: 'http://www.3gpp.org/ftp/Specs/archive/29_series/29.xyz/'
 
servers:
  - url: '{apiRoot}/nniaf-analytics/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 4.4.1 of 3GPP TS 29.501

这个文件头包含了所有关键元数据：API标题、完整的语义化版本号、版权信息、指向3GPP TS规范原文的链接，以及最重要的servers对象，它使用变量{apiRoot}定义了API的入口URI。

3.2 模块化与引用 (Clause 5.3.6) - 构建可维护的“乐高积木”

一个复杂的API可能有上百个数据模型。如果全部写在一个文件里，将会难以维护。规范鼓励使用$ref进行模块化设计。

规范原文引用 (Clause 5.3.6): Open API specification files may contain references to fragments of other 3GPP-defined Open API specification files. Such references shall be formatted to refer to local files stored on the same folder.

小王的设计思考： Nniaf_Analytics服务需要用到很多通用数据类型，比如Supi（用户永久标识）、PlmnId（公众陆地移动网络ID）。小王不需要自己重新定义它们，他可以直接引用由TS 29.571定义的“通用数据类型库”。

components:
  schemas:
    AnalyticsJob:
      type: object
      properties:
        supi:
          # 从通用库引用Supi类型
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
        servingPlmnId:
          # 从通用库引用PlmnId类型
          $ref: 'TS29571_CommonData.yaml#/components/schemas/PlmnId'```
这种引用机制使得API定义变得高度模块化和可复用，大大提高了规范制定的效率和一致性。
 
### 3.3 定义数据模型 (Schemas) - API的“基因序列”
 
这是YAML文件中最核心、最庞大的部分——`components/schemas`。它将第5.2节中的数据结构表，转化为精确的OpenAPI Schema对象。
 
> > **规范原文引用 (Clause 5.3.9 Structured data types):**
> > For a structured data type, ... the OpenAPI Specification file shall contain a definition in the components/schemas clause defining a schema with the name of the structured data type as key.
 
**小王的设计思考（`JobStatus`枚举的完整定义）：**
```yaml
    JobStatus:
      anyOf:
        - type: string
          enum:
            - PENDING
            - IN_PROGRESS
            - COMPLETED
            - FAILED
        - type: string
      description: |
        Represents the status of an analytics job. Possible values are:
        - PENDING: The job is created but not yet started.
        - IN_PROGRESS: The job is currently being processed.
        - COMPLETED: The job has finished successfully.
        - FAILED: The job terminated with an error.

注意这里的anyOf结构，这是3GPP为了前向兼容性设计的巧妙机制。它允许一个枚举值既可以是当前已定义的几个值之一，也可以是一个普通的string。这样，如果未来JobStatus增加了新的枚举值（如CANCELLED），旧的、不认识这个新值的客户端仍然可以将其当作一个普通字符串来处理，而不会导致解析失败。

总结：从规范到契约，文档即代码

第5章是连接“设计思想”与“工程实现”的坚实桥梁。它通过一套极其详尽和严谨的规则，确保了所有5G SBI API的“说明书”不仅是写给人看的，更是写给机器看的、可以被严格执行的“数字契约”。

通过对本章的学习，小王成功地将Nniaf_Analytics服务的所有设计细节，转化为一份高质量的nniaf-analytics.yaml文件。这份文件：

  • 命名统一：遵循了严格的大小写和分隔符约定。
  • 结构清晰：通过标准化的表格和资源树，宏观和微观结构都一目了然。
  • 格式标准：完全符合OpenAPI 3.0和YAML的语法，为自动化工具链的使用铺平了道路。
  • 设计健壮：内置了前向兼容性设计，并与通用数据类型库实现了模块化解耦。

这份YAML文件，就是小王交付给开发、测试、运维团队的“单一事实来源”(Single Source of Truth)。它真正践行了“文档即代码”的现代软件工程理念。

在下一篇文章中，我们将探讨第6章 (Requirements for secure API design)，为我们精心设计的API大厦，构建一套坚不可摧的“安防系统”。

FAQ

Q1：为什么3GPP选择YAML而不是JSON来编写OpenAPI文件？ A1：规范明确规定使用YAML格式。主要原因是可读性。YAML使用缩进来表示层级关系，省略了大量的括号和逗号，使得文件结构更加清晰，尤其是在描述复杂嵌套的数据模型时。它还支持注释和多行字符串，这对于编写包含大量描述性文本的规范文档来说非常友好。虽然JSON和YAML在数据模型上是等价的，并且可以相互转换，但YAML对于人类作者和读者来说，体验通常更好。

Q2：第5.2节中的那些表格和最终的OpenAPI YAML文件是什么关系？ A2：它们是“设计稿”和“最终成品”的关系。第5.2节的表格化描述方法，是3GPP内部制定规范时使用的一套标准化流程，它帮助规范制定者（如小王）以结构化的方式思考和呈现API的设计，便于在工作组内部评审和讨论。而这份表格化设计稿的最终“编译”或“渲染”结果，就是作为规范附件发布的、符合第5.3节要求的OpenAPI YAML文件。

Q3：为什么枚举类型要使用复杂的anyOf结构，而不是直接使用enum关键字？ A3：这是为了解决API演进中的前向兼容性 (Forward Compatibility)问题。假设V1版本的JobStatus有4个值，一个严格的V1客户端只认识这4个值。如果V2版本增加了一个新的状态CANCELLED，当V2的服务器返回这个新状态给V1的客户端时，如果Schema只用了enum，客户端的校验器会认为这是一个非法值而拒绝整个消息。而使用了anyOf结构，它告诉校验器：这个字段的值，可以是enum列表里的一个，也可以是任意一个字符串。这样，V1客户端虽然不理解CANCELLED的业务含义，但可以把它当作一个普通字符串接受下来，避免了程序崩溃，保证了基本的互操作性。

Q4：info.version和servers.url中的版本号有什么区别？ A4：这是一个非常关键的区别。

  • info.version: 必须是完整的语义化版本号，例如 1.2.3。它精确地标识了这份OpenAPI文件所描述的API的详细版本。
  • servers.url中的版本号: 必须只包含主版本号 (MAJOR version)，例如 v1。它定义了API的访问入口。 这种分离的设计，正是实现“后向兼容升级时URI不變”这一核心策略的关键。

Q5：如果我的API非常简单，还需要遵循第5章中所有这些复杂的表格和规则吗？ A5：是的，必须遵循。TS 29.501的原则和指南适用于所有5GC SBI API，无论其业务逻辑的复杂程度如何。这种严格的一致性是整个SBA生态系统能够健康运作的基础。即使是一个简单的API，遵循这些规则也能确保其命名规范、结构清晰、具备良好的可扩展性和可维护性，并且能够无缝地融入3GPP的自动化工具链生态。这是保证5G核心网作为一个整体，而非一堆独立组件集合的关键所在。

关系图谱