跳到主要内容
版本：Latest(v3.0) 🔥

API Document Validation

1. API Swagger 文档改进事项​

1.1 API Endpoint(Method + Path) 的描述不足​

  • 多数 API 的 Summary / Description 字段为空或内容无意义

    • 예시:

      • "Summary": "modifyAdminFailCntReset" (由 JAVA 框架自动生成)

      • Description: “” (为空)

      • (以下示例为 bw-core-auth Swagger 文档)

      • (良好构建的 Swagger 示例)

  • 문제점:
    • 意义不明的 Summary 使得 API 用途区分困难（存在多个相似 Summary 的 API）
    • “这个 API 是为了什么而创建的”，“在什么业务场景中使用” 一目了然
    • 문서 기반 협업·자동화의 가치를 활용할 수 없음 → Swagger는 있지만, 실질적으로는 구전/샘플 JSON에 의존하는 형태

1.2 Request Body(JsonNode) Parameter 미정의​

  • 该参数是“数组/对象/数字/字符串” ALL Type JSON 트리 메타 정보(모든 요청을 받을 수 있는 형태)만 제공

    • 예시: Bizapi-test-prod 的 “/v1/search/dsnet/addr-avail-prod-list 외 3개 Endpoint”
  • 문제점:
    • 从查看 Swagger 的客户端开发者的角度，无法识别需要输入哪些键/值
    • “请求示例请求”，“字段说明请求”等 커뮤니케이션 비용 발생

1.3 동일 Endpoint의 다중 Swagger 파일 중복 정의​

  • 在不同的 Swagger 文件中，重复定义相同路径/方法/功能的 API

    • 示例: /v1/op/cert-sms-confirm, /v1/op/cert-sms-send 在 auth 和 bizapi-test-auth 中重复

  • 问题：

    • 不清楚应该信任哪个 Swagger 文件
    • 随着时间推移，可能只修改一方文件的 스펙 드리프트(drift) 风险
    • 修改相同 API 时 여러 파일을 동시에 수정해야 하는 유지보수 비용

2. 점진적 개선 타임라인 (4개월)​

2.1 ~2개월차: Endpoint 문서 품질 개선 (Summary / Description)​

  • 목표
    • 所有主要 API 填写“人可以理解的”摘要/描述，以便一目了然地了解用途和场景
  • 주요 액션
    • 摘要：将自动生成的方法名样式（如 modifyAdminFailCntReset）更改为基于业务术语（例如：modifyAdminFailCntReset → 管理员登录失败次数初始化）
    • 描述：在空描述中添加至少 1~2 行以上的详细说明
      • “在什么情况下由谁调用”
      • “核心参数/限制简单整理”
  • 검증/운영 방식

    • 通过 APIM 文档验证检查摘要/描述的存在性、最小长度等

    • 초기에는 Warning으로 시작(Slack 공유)，逐步转换错误

    • （以下是应用 APIM “检查操作描述”后的验证结果）

    • （通过 Slack 渠道将该结果分享给相关人员）

  • 기대 효과
    • 仅通过 Swagger 就可以选择使用哪个 API
    • 之后为合并重复 API 和移除 JsonNode 的工作提供基础信息

2.2 ~3개월차: JsonNode Request Body 개선 (핵심 필드 명세화)​

  • 목표
    • 在基于 JsonNode 的请求体中，关于“业务核心 API”的 최소한의 필드 계약을 Swagger에 나타냄
  • 주요 액션
    • 识别使用 JsonNode 的 API
      • /v1/search/dsnet/addr-avail-prod-list, /v1/search/dsnet/hq-gift-list, /v1/search/dsnet/prom-list 等
    • 仅将“所需的核心字段”分离为单独的模式
    • 示例：添加 AddrAvailProdRequest 等定义
AddrAvailProdRequest:
  type: object
  properties:
    addrId:
      type: string
      description: "地址 ID"
    svcType:                 
      type: string
      description: "服务类型"
  required: [addrId, svcType]    # 核心参数声明 
  additionalProperties: true     # 其他键允许为任何值

  • 明确 addrId、svcType、userId 等必填字段

  • 其他附加字段可灵活允许为 additionalProperties: true / extra 字段等

  • 검증/운영 방식
    • 使用 Spectral 将对 #/definitions/JsonNode 的直接引用处理为警告

  • 新的 API 将 JsonNode 的使用处理为 Warning/Error，并指导必须使用具体的模式

    • （以下是应用 APIM “Check JsonNode Schema” 规则集后的验证结果）

    • （通过 Slack 渠道将该结果分享给相关人员）

  • 기대 효과
    • 客户端开发者仅通过 Swagger 就能知道应该输入哪些键/值
    • 减少以样本 JSON 请求为主的口头文化

2.3 ~4개월차: 중복 API 탐지 및 제거​

  • 목표
    • 识别在不同 Swagger 文件中重复定义的 Endpoint，并进行整合/整理以增加可重用性
  • 주요 액션
    • 通过即将生成的重复 API 检测规则集，自动提取基于 method + path 的重复 Endpoint 列表
    • 例如：/v1/op/cert-sms-confirm 和 /v1/op/cert-sms-send 在 auth 和 bizapi-test-auth 两个文件中存在
    • 之后，团队将进行审查并决定哪些文件需要被标记为弃用后删除
  • 검증/운영 방식
    • 在 CI 中生成重复 Endpoint 报告（Warning 或失败标准需组织达成一致）
    • 新的 API 将指导“确认是否重用现有路径 → 新建”的流程
  • 기대 효과
    • 解决同一功能的 API 分散在多个文档中的情况
    • 在变更时明确“需要修改哪里”，降低维护成本
    • 整理构建公共/共享 API 库的基础