oastools

oastools

Note: this is still a work in progress and all code is being generated by Claude Code using claude-4-5-sonnet

OpenAPI Specification (OAS) tools for validation, parsing, and joining.

Features

• Validate - Validate OpenAPI specification files for correctness
• Parse - Parse and analyze OpenAPI specifications
• Join - Join multiple OpenAPI Specification documents (planned)

Supported OpenAPI Specification Versions

This tool supports all official OpenAPI Specification releases:

Note: Release candidate versions (e.g., 3.0.0-rc0, 3.1.0-rc1) are detected but not officially supported.

Installation

From Source

git clone https://github.com/erraggy/oastools.git
cd oastools
make install

Using Go

go install github.com/erraggy/oastools/cmd/oastools

Usage

# Show help
oastools help

# Validate an OpenAPI spec
oastools validate openapi.yaml

# Parse an OpenAPI spec
oastools parse openapi.yaml

# Join multiple OpenAPI specs
oastools join base.yaml extensions.yaml

Example Usage

go run github.com/erraggy/oastools/cmd/oastools validate testdata/invalid-oas3.yaml
OpenAPI Specification Validator
================================

File: testdata/invalid-oas3.yaml
Version: 3.0.3

Errors (12):
  ✗ document: oas 3.0.3: missing required field 'info.version': Info object must have a version string per spec
  ✗ document: oas 3.0.3: invalid path pattern 'paths.items': path must begin with '/'
  ✗ document: oas 3.0.3: missing required field 'paths.items.get.responses': Operation must have a responses object
  ✗ document: oas 3.0.3: invalid parameter 'paths.items.get.parameters[0]': path parameters must have 'required: true' per spec
  ✗ document: oas 3.0.3: missing required field 'paths.items.get.parameters[1].in': Parameter must specify location (query, header, path, cookie)
  ✗ document: oas 3.0.3: missing required field 'paths.items.post.requestBody.content': RequestBody must have at least one media type
  ✗ document: oas 3.0.3: duplicate operationId 'createItem' at 'paths./users.get': previously defined at 'paths.items.post' (operationIds must be unique across all operations)
  ✗ info.version: Info object must have a version
    Spec: https://spec.openapis.org/oas/v3.0.3.html#info-object
  ✗ paths.items: Path must start with '/'
    Spec: https://spec.openapis.org/oas/v3.0.3.html#paths-object
  ✗ paths.items.post.requestBody: RequestBody must have a content object with at least one media type
    Spec: https://spec.openapis.org/oas/v3.0.3.html#request-body-object
  ✗ paths.items.get.parameters[0]: Path parameters must have required: true
    Spec: https://spec.openapis.org/oas/v3.0.3.html#parameter-object
  ✗ paths.items.post: Duplicate operationId 'createItem' (first seen at paths./users.get)
    Spec: https://spec.openapis.org/oas/v3.0.3.html#operation-object

Warnings (3):
  ⚠ paths.items.post: Operation should have a description or summary for better documentation
    Spec: https://spec.openapis.org/oas/v3.0.3.html#operation-object
  ⚠ paths./users.get: Operation should have a description or summary for better documentation
    Spec: https://spec.openapis.org/oas/v3.0.3.html#operation-object
  ⚠ paths.items.get: Parameter 'id' is declared as path parameter but not used in path template
    Spec: https://spec.openapis.org/oas/v3.0.3.html#path-item-object

✗ Validation failed: 12 error(s), 3 warning(s)
exit status 1

Limitations

External References

• HTTP(S) References Not Supported: The parser currently only supports local file references for external $ref values. References starting with http:// or https:// are not yet supported.
• Security: External file references are restricted to the base directory and its subdirectories to prevent path traversal attacks.

Development

Prerequisites

• Go 1.24 or higher
• make (optional, but recommended)

Building

# Build the binary
make build

# Run tests
make test

# Run linter
make lint

# Format code
make fmt

Project Structure

.
├── cmd/oastools/       # CLI entry point
├── internal/           # Private application code
│   ├── validator/      # OpenAPI validation logic
│   ├── parser/         # OpenAPI parsing logic
│   └── joiner/         # OpenAPI joining logic
├── pkg/                # Public library code
└── testdata/           # Test fixtures and sample specs

License

MIT