Add comprehensive OpenAPI 3.0 specification for Customer Data Service API

[Copilot]

Purpose

Establishes formal API contract. CDS lacked machine-readable API documentation, preventing SDK generation, API testing tool integration, and contract-driven development.

Goals

Provide complete OpenAPI 3.0 specification covering all endpoints, authentication schemes, request/response schemas, error formats, and multi-tenancy support.

Approach

Enhanced api/customer-data-service.yaml (703→2,340 lines):

• Added missing endpoint groups: Profile Schema Management (complete CRUD), health checks, /profiles/Me endpoints, admin sync operations
• Documented authentication: Bearer JWT (scope-based) + Basic Auth (admin sync)
• Defined 20+ schemas: Profile, SchemaAttribute, UnificationRule, EnrichmentRule, Consent, ConsentCategory, Device, Event
• Standardized error responses with machine-readable codes
• Added query parameters: filtering, pagination, selective attributes
• Created reusable components (ScopePathParam) to eliminate duplication
• Multi-tenant URL structure: /t/{tenant}/cds/api/v1/*

Created api/README.md:

• SDK generation examples (TypeScript, Python, Java, Go)
• Interactive documentation setup (Swagger UI, Redoc)
• Authentication flow with scope requirements
• API testing tool integration guide

Validation: OpenAPI 3.0 compliant via swagger-cli

User stories

• Developers generate type-safe client SDKs in their language of choice
• API consumers browse interactive documentation with request/response examples
• QA engineers import spec into Postman/Insomnia for automated testing
• Platform teams validate implementation against contract
• New engineers onboard via comprehensive, machine-readable documentation

Release note

Added comprehensive OpenAPI 3.0 specification documenting all CDS API endpoints, authentication schemes, schemas, and error formats. Enables SDK generation, interactive documentation, and API testing tool integration.

Documentation

N/A - This PR adds the API documentation itself. The api/README.md provides usage instructions for the specification.

Training

N/A - Documentation change only. Training content should reference the new OpenAPI spec for API contract details.

Certification

N/A - Infrastructure documentation enhancement, no user-facing feature changes requiring certification updates.

Marketing

N/A - Internal API documentation improvement

Automation tests

• Unit tests: N/A (YAML specification file)
• Integration tests: N/A (documentation only)
• Validation: OpenAPI 3.0 spec validated via swagger-cli

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines? N/A (documentation only)
• Ran FindSecurityBugs plugin and verified report? N/A (no executable code)
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets? yes

Samples

N/A - The OpenAPI spec itself serves as the canonical reference. README includes authentication examples and SDK generation commands.

Related PRs

None

Migrations (if applicable)

N/A - Additive documentation, no breaking changes

Test environment

Validated on:

• OpenAPI 3.0 validator (swagger-cli v4.0.4)
• Node.js v18+ (for validation tooling)

Learning

• Analyzed internal route handlers to extract complete endpoint inventory
• Studied authentication middleware to document JWT scope requirements and Basic Auth flows
• Reviewed error handling patterns for standardized response format
• Applied OpenAPI 3.0 reusable components pattern for parameter deduplication

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Create API definition</issue_title>
<issue_description>CDS currently doesn’t have a formal API contract. We should add an OpenAPI (Swagger) specification to clearly define all endpoints, request/response schemas, authentication, and error formats</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Create API definition #181

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}