API Document Validation

1. Cải tiến tài liệu API Swagger

1.1 Thiếu mô tả cho API Endpoint (Phương thức + Đường dẫn)

• Nhiều trường Summary / Description của API bị trống hoặc có nội dung không có ý nghĩa

  • 예시:

    • "Summary": "modifyAdminFailCntReset" (Tự động tạo bởi JAVA Framework)

    • Description: “” (trống)

    • (Ví dụ dưới đây là tài liệu Swagger của bw-core-auth)

    • (Ví dụ Swagger được cấu trúc tốt)

• 문제점:
  • Summary không có ý nghĩa khiến việc phân biệt mục đích của API trở nên khó khăn (có nhiều API có Summary tương tự)
  • Không thể nhận biết "API được tạo ra để làm gì", "được sử dụng trong kịch bản công việc nào" chỉ bằng một cái nhìn
  • 문서 기반 협업·자동화의 가치를 활용할 수 없음 → Swagger는 있지만, 실질적으로는 구전/샘플 JSON에 의존하는 형태

1.2 Request Body(JsonNode) Parameter 미정의

• Parameter này là “mảng hay đối tượng hay số hay chuỗi” ALL Type JSON 트리 메타 정보(모든 요청을 받을 수 있는 형태)만 제공

  • 예시: của Bizapi-test-prod “/v1/search/dsnet/addr-avail-prod-list 외 3개 Endpoint”
• 문제점:
  • Từ góc độ của nhà phát triển khách hàng xem Swagger, không thể nhận biết được cần phải nhập vào khóa/giá trị nào
  • “Yêu cầu mẫu Request”, “Yêu cầu mô tả trường” v.v. 커뮤니케이션 비용 발생

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

• API với cùng đường dẫn/phương thức/chức năng được định nghĩa trùng lặp trong các tệp Swagger khác nhau

  • Ví dụ: /v1/op/cert-sms-confirm, /v1/op/cert-sms-send bị trùng lặp trong auth và bizapi-test-auth

• Vấn đề:

  • Không rõ nên tin tưởng tệp Swagger nào
  • Có nguy cơ chỉ một tệp bị sửa đổi theo thời gian 스펙 드리프트(drift)
  • Khi sửa đổi API giống nhau 여러 파일을 동시에 수정해야 하는 유지보수 비용

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

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

• 목표
  • Fill in “human-readable” Summary/Description for all major APIs to make their purpose and scenarios easily understandable.
• 주요 액션
  • Summary: Change the automatically generated method name style (e.g., modifyAdminFailCntReset) to business terminology (e.g., modifyAdminFailCntReset → Khởi tạo số lần đăng nhập của quản trị viên thất bại).
  • Description: Add at least 1-2 lines of detailed explanation to the empty Description.
    • “In what situation and by whom it is called”
    • “Brief summary of key parameters/limitations”
• 검증/운영 방식

  • Validate the existence of Summary/Description and minimum length through APIM documentation checks.

  • 초기에는 Warning으로 시작(Slack 공유), gradually transition to error handling.

  • (Below is the validation result after applying APIM “Check Operation Description”)

  • (Share the results with the responsible parties through the Slack channel)

• 기대 효과
  • It should be possible to choose which API to use just by looking at Swagger.
  • Subsequently, secure the foundational information for the integration of duplicate APIs and the removal of JsonNode.

---

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

• 목표
  • Among the JsonNode-based Request Body, focus on the “core business API” 최소한의 필드 계약을 Swagger에 나타냄.
• 주요 액션
  • Identify APIs using JsonNode.
    • /v1/search/dsnet/addr-avail-prod-list, /v1/search/dsnet/hq-gift-list, /v1/search/dsnet/prom-list, etc.
  • Separate only the “necessary core fields” into a separate schema.
  • Example: Add definitions such as AddrAvailProdRequest.

AddrAvailProdRequest:
  type: object
  properties:
    addrId:
      type: string
      description: "ID địa chỉ"
    svcType:                 
      type: string
      description: "Loại dịch vụ"
  required: [addrId, svcType]    # Khai báo tham số chính 
  additionalProperties: true     # Cho phép các khóa khác

• Specify only the required fields such as addrId, svcType, userId.

• Allow other additional fields flexibly with additionalProperties: true / extra fields, etc.

• 검증/운영 방식
  • Handle direct references to #/definitions/JsonNode as a Warning with Spectral.

• Trong API mới, việc sử dụng JsonNode sẽ được xử lý như Warning/Error và phải được hướng dẫn sử dụng schema cụ thể.

  • (Dưới đây là kết quả kiểm tra sau khi áp dụng Ruleset “Check JsonNode Schema” của APIM)

  • (Kết quả này được chia sẻ với các nhân viên qua kênh Slack)

• 기대 효과
  • Các nhà phát triển client có thể biết được họ cần nhập key/value nào chỉ bằng cách nhìn vào Swagger.
  • Giảm bớt văn hóa truyền miệng chủ yếu dựa trên yêu cầu JSON mẫu.

---

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

• 목표
  • Xác định các Endpoint được định nghĩa trùng lặp trong các tệp Swagger khác nhau, hợp nhất và sắp xếp để tăng khả năng tái sử dụng.
• 주요 액션
  • Tự động trích xuất danh sách Endpoint trùng lặp dựa trên method + path bằng Ruleset phát hiện API trùng lặp (sẽ được tạo).
  • Ví dụ: /v1/op/cert-sms-confirm, /v1/op/cert-sms-send tồn tại trong hai tệp auth, bizapi-test-auth.
  • Sau đó, quyết định trong cuộc họp nhóm và chính sách về tệp nào sẽ được đánh dấu là deprecated và xóa.
• 검증/운영 방식
  • Tạo báo cáo Endpoint trùng lặp trong CI (Warning hoặc thất bại theo sự đồng thuận của tổ chức).
  • API mới sẽ được hướng dẫn theo quy trình “kiểm tra xem có tái sử dụng đường dẫn hiện có hay không → tạo mới”.
• 기대 효과
  • Giải quyết tình huống API cùng chức năng bị phân tán trong nhiều tài liệu.
  • Khi có thay đổi, rõ ràng hơn về “nơi cần sửa đổi”, giảm chi phí bảo trì.
  • Tổ chức cơ sở để xây dựng thư viện API chung/chia sẻ.