OAPI-Codegen
OAPI-Codegen
OpenAPI code generation for Go API services
OAPI-Codegen is used in the Control Plane to generate server and client code from OpenAPI specifications, ensuring that APIs are consistent, well-documented, and type-safe.
OpenAPI-driven development
The Control Plane follows an OpenAPI-first approach, where API specifications are written first and code is generated from those specifications.
Overview
OAPI-Codegen is a utility that generates Go code from OpenAPI 3.0 specifications, bridging the gap between API design and implementation. It supports various targets including server stubs, client code, type definitions, and spec validation.
🔄 API Consistency
Ensures API implementation matches the OpenAPI specification exactly.
🏗️ Automatic Code Generation
Reduces boilerplate code and implementation errors.
📝 Type Safety
Generates Go types that match API request and response schemas.
🧩 Framework Integration
Works with multiple web frameworks including Gofiber, Echo, and Chi.
🔍 Validation
Validates request data against the schema defined in the OpenAPI spec.
📚 Self-documenting
OpenAPI spec serves as living documentation for the API.
Why OAPI-Codegen?
⚡ Developer Productivity
Eliminates repetitive boilerplate code, allowing developers to focus on business logic rather than API plumbing.
📝 Contract-First Development
Enforces a contract-first approach where API design decisions are made deliberately before implementation.
🧪 Reduced Testing Burden
Generated code is already tested by the library maintainers, reducing the need for extensive testing of API mechanics.
🚫 Error Prevention
Prevents common API implementation errors like missed validation, incorrect types, or forgotten endpoints.
🔁 Consistency Across Services
Ensures all services follow the same patterns for API implementation, improving maintainability.
📋 Documentation as Code
API documentation is generated from the same source as the code, ensuring it's always accurate and up-to-date.
Integration in the Control Plane
API-first development workflow
Control Plane developers define the API contract in OpenAPI specification files first, then generate server and client code, ensuring the implementation aligns with the design.
Configuration Options
Code generation control
OAPI-Codegen offers fine-grained control over the generated code through a configuration file.
Best Practices in the Control Plane
📜 API-First Development
Define the API contract in OpenAPI before writing any implementation code.
🔄 Regenerate on Spec Changes
Automate code regeneration as part of the build process when specs change.
🧩 Separate Generated Code
Keep generated code in separate files (*.gen.go) to distinguish from hand-written code.
🚫 Don't Modify Generated Code
Implement custom logic by implementing interfaces, not by modifying generated code.
📚 Consistent Error Formats
Use shared error schemas across all APIs for consistent client experiences.
✅ Validate Input Data
Use the generated validation functions for all incoming data.
Integration with Gofiber
Framework integration
OAPI-Codegen generates code specifically tailored for Gofiber in the Control Plane, making integration seamless.
Related Resources
OpenAPI Specification
The foundation of API design in the Control Plane.
Gofiber
The high-performance web framework used with OAPI-Codegen.
Swagger UI
Interactive API documentation generated from OpenAPI specs.
API Design Patterns
Best practices for API design in the Control Plane.