メインコンテンツまでスキップ
バージョン: Latest(v3.0) 🔥

API Document Validation

1. API Swagger ドキュメントの改善点​

1.1 API エンドポイント (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 미정의​

  • この Parameter が “配列なのか/オブジェクトなのか/数値なのか/文字列なのか” ALL Type JSON 트리 메타 정보(모든 요청을 받을 수 있는 형태)만 제공

    • 예시: Bizapi-test-prod の “/v1/search/dsnet/addr-avail-prod-list 외 3개 Endpoint”
  • 문제점:
    • Swagger を見るクライアント開発者の立場では、どのキー/値を入れるべきかは認識できない
    • “Request サンプルリクエスト”、 “フィールド説明リクエスト” など 커뮤니케이션 비용 발생

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「Check Operation Description」適用後の検証結果）

    • （この結果を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に対する直接参照をWarning処理

  • 新しいAPIではJsonNodeの使用をWarning/Errorとして処理し、必ず具体的なスキーマを使用するようにガイド

    • （以下はAPIM “Check JsonNode Schema”ルールセット適用後の検証結果）

    • （この結果をSlackチャンネルを通じて担当者に共有）

  • 기대 효과
    • クライアント開発者がSwaggerだけを見ても、どのキー/値を入れるべきかがわかる
    • サンプルJSONリクエスト中心の口伝文化の減少

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

  • 목표
    • 異なるSwaggerファイルに重複定義されたエンドポイントを特定し、統合/整理して再利用性を向上
  • 주요 액션
    • 重複API検出ルールセット（生成予定）により、method + path基準の重複エンドポイントリストを自動抽出
    • 例: /v1/op/cert-sms-confirm, /v1/op/cert-sms-sendがauth、bizapi-test-authの2つのファイルに存在
    • 後に、チームレビューおよびポリシー決定でどのファイルをdeprecated処理後に削除するかを決定
  • 검증/운영 방식
    • CIで重複エンドポイントレポートを生成（Warningまたは失敗基準の組織合意）
    • 新しいAPIは「既存パス再利用の有無確認→新規作成」の流れでガイド
  • 기대 효과
    • 同じ機能のAPIが複数の文書に散らばっている状況を解消
    • 変更時に「どこを修正すべきか」が明確になり、保守コストが削減
    • 共通/共有APIライブラリ構築の基盤整理