Research-Stack/4-Infrastructure/NoDupeLabs/docs/api/OPENAPI.md

OpenAPI Specification Documentation

This document describes the NoDupeLabs API specification compliance with OpenAPI Specification 3.1.2 (September 2025).

Overview

NoDupeLabs implements the OpenAPI Specification 3.1.2 for documenting its CLI commands and plugin system. While NoDupeLabs is primarily a library/CLI tool (not an HTTP API), the OpenAPI spec provides a machine-readable format for:

• CLI command documentation
• Plugin metadata schemas
• Error response standardization
• Future HTTP API compatibility

Specification Location

• Primary: docs/openapi.yaml
• Version: OpenAPI 3.1.2
• Format: YAML

Compliance Level

This implementation follows OpenAPI 3.1.2 strictly:

Required Fields (OAS 3.1.2 §4.8.1)

Field	Status	Implementation
openapi	✅	3.1.2
info	✅	Title, version, description, license
paths	✅	CLI command paths
components	✅	Schemas, security schemes

Optional Fields

Field	Status	Implementation
servers	✅	Local CLI server placeholder
tags	✅	Core, Plugin, Config
webhooks	N/A	Not applicable
externalDocs	✅	Referenced in info

API Structure

Paths

Path	Method	Operation	Description
/version	GET	getVersion	Show version info
/plugin	GET	listPlugins	List loaded plugins

Schemas

VersionInfo

type: object
required: [version]
properties:
  version: string    # Semantic version
  platform: string   # Drive type (ssd/hdd)
  cores: integer    # CPU cores
  ram_gb: integer  # RAM in GB

PluginInfo

type: object
required: [name]
properties:
  name: string
  version: string
  type: enum[similarity, storage, command, time_sync]

Error

type: object
required: [message]
properties:
  code: integer
  message: string

Usage

Viewing the Specification

# View raw YAML
cat docs/openapi.yaml

# Validate with Redocly
npx redocly lint docs/openapi.yaml

# View with Swagger UI
npx swagger-ui-static -o docs/openapi.yaml

Generating Documentation

# Install OpenAPI tools
pip install openapi-spec-validator

# Validate spec
python -c "import openapi_spec_validator; openapi_spec_validator.validate_spec_file('docs/openapi.yaml')"

CI Integration

The OpenAPI spec is validated in CI via:

# Validate YAML syntax
python tools/core/enforce_yaml_spec.py --check docs/openapi.yaml

Extensions

NoDupeLabs-specific extensions use the x-nodupelabs prefix:

x-nodupelabs:
  stability: stable  # STABLE, BETA, EXPERIMENTAL
  since: 1.0.0     # Version when added

Security Schemes

Scheme	Type	Usage
API_KEY_REMOVED	API Key	Header-based authentication

References

• OpenAPI Specification 3.1.2
• OpenAPI Initiative
• JSON Schema Draft 2020-12

Version History

Version	Date	Changes
1.0.0	2026-02-14	Initial OpenAPI 3.1.2 spec