The Challenge
A microservices architecture with 20+ projects and hundreds of Lambda functions needed a way to keep SDKs and API documentation in sync with the actual implementation. Manual SDK maintenance was error-prone and documentation was perpetually outdated. The system needed to support three different API layers:
- Public-facing APIs for external consumers
- Internal APIs for inter-service communication
- Control plane APIs for administrative functions
The Solution
I designed a four-stage automated pipeline that generates OpenAPI specs at build time, merges them into complete API definitions, generates SDKs in multiple languages, and publishes everything automatically.
Stage 1: OpenAPI Spec Generation
Each microservice pipeline uses source generators to automatically produce OpenAPI specs from Lambda function annotations at build time. This ensures the spec always matches the actual implementation—no manual YAML editing required.
The specs are uploaded to an S3 bucket, with separate specs generated for each API layer (public, internal, control plane).
Stage 2: OpenAPI Merge
S3 events trigger an EventBridge rule that invokes a Step Functions workflow. A Lambda function merges individual OpenAPI specs into complete API definitions for each layer. DynamoDB is used with Step Functions to debounce overlapping or frequent incoming events, preventing redundant SDK builds.
The merged specs are published to a separate bucket, triggering the next stage of the pipeline.
Stage 3: SDK Generation
EventBridge triggers an AWS CodePipeline that generates TypeScript and C# SDKs using Microsoft's Kiota tooling. The pipeline uses SemVer for incremental builds, publishing:
- Public SDK to npm and NuGet for external consumers
- Internal packages to CodeArtifact for inter-service use
GitHub releases are created with SemVer-numbered tags, and package release events trigger the documentation pipeline.
Stage 4: Documentation & Website
Public SDK releases trigger a final pipeline that regenerates API documentation using DocFX for C# SDKs. The documentation site is updated with the latest version numbers and SDK links, then published to S3 with CloudFront cache invalidation.
SNS notifications alert the team to new releases via email.
Key Outcomes
Zero Manual SDK Maintenance
SDKs are always in sync with the API implementation—no manual updates required.
Always-Current Documentation
API docs regenerate automatically with every release, eliminating documentation drift.
Multi-Language Support
TypeScript and C# SDKs generated from the same source of truth.
Separation of Concerns
Public, internal, and control plane APIs managed independently with appropriate access controls.