Contract first
Contract first approach with full explicit control over OAS configuration
Overview
The OpenAPI Specification (OAS) contract can be created using dedicated tools; however, the preferred approach is code-first, ensuring the contract is derived directly from the service implementation. This approach maintains consistency between code and API documentation while reducing manual effort.
Key principles of the contract-first approach include:
- The OAS contract file is stored within the service's repository.
- Endpoint configurations are defined alongside the service code, ensuring synchronization.
Service Code Generation
To simplify service implementation for developers, an automated generator is used to produce the required C# code. This ensures efficiency, consistency, and repeatability.
The generator helps produce:
- C# DTOs – Data Transfer Objects used in API contracts.
- C# API Controllers – Controllers exposing endpoints based on the OAS contract.
- C# Interfaces – Abstract definitions for service logic, called by controllers and implemented by developers.
The generator is designed to allow repeated execution without overwriting manually implemented business logic, ensuring a safe and iterative development process.
Code Generation Tool
The code generator and related documentation are available in the following repository (project migration is planned):
Refer to the repository for examples and detailed usage instructions.
Naming Conventions
Consistent naming conventions are crucial for maintainability and readability. The same conventions applied to other API components should be followed here as well.
Refer to the naming guidelines:
Naming Conventions
By leveraging the contract-first approach and automated code generation, developers can focus on implementing business logic while ensuring the API remains consistent and compliant with the defined specifications.