Contract API Management and Validation

This project provides a comprehensive toolkit for managing and validating API contracts using the OpenAPI specification. The repository is structured to support microservices and tag-based organization for optimal Java interface generation.

Start here: Vega Contract-First Experience Guide — https://vegainvestments.atlassian.net/wiki/x/EQByVg

Quick Links

Documentation

• Swagger UI (requires authentication)
• Redocly Documentation
• Vacuum Changes Report
• Vacuum Quality Report

Installation

1. Clone the repository:

   git clone https://github.com/vegainvestments/contract

2. Navigate to the project directory:

   cd contract

3. Install Node.js
4. Set up Yarn Berry:

   corepack enable
   yarn set version berry

5. Install dependencies:

   yarn install

Repository Structure

contract/
├── entry/                            # Source OpenAPI specs (author here)
│   ├── components/                   # Shared components across all services
│   │   ├── UUID.yaml
│   │   ├── DateTime.yaml
│   │   ├── TimeFrame.yaml
│   │   └── ...
│   ├── <service>/
│   │   ├── index.yaml                # Service root (servers, security, tags, path $refs)
│   │   ├── paths/                    # Per-tag path files (operations live here)
│   │   │   └── v1/<tag>.yaml
│   │   └── models/                   # Per-file models (requests, responses, types, enums)
│   │       └── v1/{requests|responses|types|enums}/*.yaml
├── bundled/                          # Generated per-service bundles (DO NOT EDIT)
│   ├── analytics.yaml
│   ├── authentication.yaml
│   └── ...
├── bundled.yaml                      # Generated joined spec (all services)
└── package.json                      # Scripts and dependencies

Key Features

• Direct model references: Path files reference models directly (no models/schemas.yaml index)
• No custom scripts: Uses industry-standard tools (Redocly, Vacuum)
• IntelliJ compatible: Relative $ref paths resolve cleanly in IDEs
• Microservice architecture: Clear separation by service under entry/

Development Workflow

1. Edit API Definitions

Edit files in the appropriate location:

• Shared components: entry/components/
• Service endpoints: entry/<service>/paths/**.yaml
• Service models: entry/<service>/models/**.yaml

Notes:

• In path files, reference models directly, for example:
  • Instead of $ref: '../../index.yaml#/components/schemas/DealResponse'
  • Use $ref: ../../models/v1/responses/DealResponse.yaml
• The legacy models/schemas.yaml aggregator has been removed.

2. Validate Your Changes

# Run all linters
yarn lint

# Run Redocly linting only
yarn lint:redocly

3. Bundle APIs

# Bundle all services and create merged specification (writes to bundled/* and bundled.yaml)
yarn bundle

4. Test the Bundle

# Run quality checks on bundled specifications
yarn test:bundle

5. View Documentation

# Open Swagger UI
yarn swagger

# Generate and view Redocly documentation
yarn docs

# View quality report
yarn report:quality

Available Scripts

Linting and Validation

• yarn lint - Run all linters (ESLint, Redocly)
• yarn lint:eslint - Run ESLint on YAML files
• yarn lint:redocly - Run Redocly OpenAPI linting

Building and Bundling

• yarn bundle - Bundle all services and merge into single spec
• yarn bundle:services - Bundle individual services only
• yarn bundle:merge - Merge bundled services using Redocly join

Testing and Reporting

• yarn test:bundle - Validate bundled specifications
• yarn report:quality - Generate and view Vacuum quality report
• yarn report:diff - Show changes in API specification

Documentation

• yarn swagger - View API in Swagger UI
• yarn docs - Generate and view Redocly documentation

Utilities

• yarn precommit - Run before committing (lint, bundle, test, stage bundled)

Adding New Endpoints

1. Identify the service and tag

   • Service: e.g., coinvest-deal
   • Tag: e.g., deal-opportunity

2. Edit the paths file

   # Edit api/coinvest-deal/tags/deal-opportunity/paths.yaml

3. Add your endpoint

   paths:
     /api/coinvest-deals/v1/deal-opportunities:
       post:
         summary: Create deal opportunity
         tags:
           - deal-opportunity
         # ... rest of operation

4. Add schemas if needed

   • Request schemas: api/coinvest-deal/components/schemas/
   • Response schemas: api/coinvest-deal/components/responses/

5. Reference shared components

   parameters:
     - $ref: '../../../components/UUID.yaml'

Java Interface Generation

The tag-based structure maps directly to Java interfaces:

• Each tag becomes a Java interface
• Operations under a tag become methods in that interface
• Clean separation enables better code generation

Pre-commit Process

The repository uses Husky for pre-commit checks:

yarn precommit  # Runs linting, bundling, testing, and stages generated files

Tools Used

• @redocly/cli - Documentation and additional validation
• openapi-merge-cli - Merging multiple OpenAPI files
• @quobix/vacuum - Quality reporting
• @pb33f/openapi-changes - Change detection

Migration Notes

• All $ref usages now use double-quoted values and target direct file references under entry/<service>/models/**/{Name}.yaml.
• The legacy flat entry/*.yaml service files have been replaced with per-service folders under entry/<service>/ with index.yaml, paths/, and models/.
• When adding new models, create a new file under the appropriate folder and reference it directly from paths or other models.

Best Practices

1. One Tag Per Directory - Keep operations organized by their tag
2. Reuse Components - Use shared components from api/components/
3. Validate Often - Run yarn lint frequently during development
4. Clear Descriptions - Document all operations and schemas
5. Consistent Naming - Follow the naming conventions enforced by linting

Troubleshooting

IntelliJ Not Resolving References

• Ensure you're using relative paths starting with ./ or ../
• Install the OpenAPI plugin for IntelliJ
• Work under the entry/ directory; references should resolve without additional configuration

Bundle Errors

• Ensure all $ref paths are correct
• Check that referenced files exist
• Run individual service bundles to isolate issues

Additional Resources

• OpenAPI Specification
• Spectral Documentation
• Redocly Documentation
• Vacuum Documentation
• Project Confluence