Skip to content

Release Notes: v0.2.0

Release Date: 2026-03-14

Overview

Traffic2OpenAPI v0.2.0 introduces a fluent builder API for programmatic OpenAPI spec construction, comprehensive spec validation using libopenapi, and multi-version output generation. These features enable more flexible workflows for generating and validating API specifications.

Highlights

  • Fluent Builder API: Programmatically construct OpenAPI 3.x specifications with type-safe, chainable methods
  • Spec Validation: Validate OpenAPI specifications using libopenapi with detailed error reporting
  • Multi-Version Output: Generate specs for multiple OpenAPI versions (3.0.3, 3.1.0, 3.2.0) simultaneously

New Features

OpenAPI Builder Package

The new pkg/openapibuilder package provides a fluent API for constructing OpenAPI specifications programmatically:

import "github.com/grokify/traffic2openapi/pkg/openapibuilder"

spec, err := openapibuilder.NewSpec(openapibuilder.Version310).
    Title("Pet Store API").
    Version("1.0.0").
    Server("https://api.petstore.io/v1").
    Components().
        Schema("Pet", openapibuilder.ObjectSchema().
            Property("id", openapibuilder.IntegerSchema().Format("int64")).
            Property("name", openapibuilder.StringSchema()).
            Required("id", "name")).
        SecurityScheme("bearerAuth").BearerAuth().BearerFormat("JWT").Done().
    Done().
    Path("/pets").
        Get().
            Summary("List all pets").
            OperationID("listPets").
            Response(200).Description("A list of pets").
                JSON(openapibuilder.ArraySchema(openapibuilder.RefSchema("Pet"))).Done().
        Done().
    Done().
    Build()

Features include:

  • SpecBuilder: Create OpenAPI specs with info, servers, paths
  • PathBuilder and OperationBuilder: Define endpoints and operations
  • SchemaBuilder: Support for all JSON Schema types (string, integer, object, array, etc.)
  • SecuritySchemeBuilder: OAuth2 flows (authorization_code, client_credentials, implicit, password)
  • Version-aware nullable handling: OpenAPI 3.0 nullable keyword vs 3.1+ type arrays

Spec Validation

The new pkg/openapi/validate package validates OpenAPI specifications using libopenapi:

import "github.com/grokify/traffic2openapi/pkg/openapi/validate"

// Validate a file
result, err := validate.ValidateFile("openapi.yaml")
if err != nil {
    log.Fatal(err)
}

if !result.Valid {
    for _, e := range result.Errors {
        fmt.Printf("Error at line %d: %s\n", e.Line, e.Message)
    }
}

CLI usage:

# Validate a single spec
traffic2openapi validate-spec openapi.yaml

# Validate all specs in a directory
traffic2openapi validate-spec ./specs/

# Strict mode (treat warnings as errors)
traffic2openapi validate-spec openapi.yaml --strict

Multi-Version Output

Generate the same specification in multiple OpenAPI versions:

import "github.com/grokify/traffic2openapi/pkg/openapi/convert"

// Generate for all supported versions
output, err := convert.AllVersions(spec)

// Or specific versions
output, err := convert.NewMultiVersionOutput(spec,
    convert.Version303, convert.Version310, convert.Version320)

// Write all versions to files
output.WriteFilesToDir("./output", "api", openapi.FormatYAML)
// Creates: api-3.0.3.yaml, api-3.1.0.yaml, api-3.2.0.yaml

CLI usage:

# Generate multiple versions
traffic2openapi generate -i traffic.ndjson -o api.yaml --versions 3.0,3.1,3.2

# Generate all supported versions
traffic2openapi generate -i traffic.ndjson -o api.yaml --all-versions

CLI Enhancements

New flags for the generate command:

Flag Description
--versions Comma-separated list of versions (3.0, 3.1, 3.2)
--all-versions Generate all supported versions
--skip-validation Skip built-in spec validation

New validate-spec command for validating OpenAPI specifications:

Flag Description
--verbose Show detailed validation results
--strict Treat warnings as errors
--warnings Show warnings (default: true)

Documentation

  • Restructured documentation for GitHub Pages (markdown source in docs/)
  • New examples in examples/builder/, examples/validation/, and examples/multiversion/

Dependencies

  • Added github.com/pb33f/libopenapi for OpenAPI parsing and validation

Upgrade Guide

This release is backwards compatible with v0.1.0. New features are additive.

To use the new validation features, generated specs are now validated by default. Use --skip-validation to disable if needed.

What's Next

Planned for future releases:

  • Additional adapters (mitmproxy, Envoy)
  • Schema merging and conflict resolution
  • OpenAPI diff with semantic comparison
  • Web UI for spec review and editing