Skip to content

CHANGELOG.md

Latest commit

 

History

History
80 lines (61 loc) · 3.2 KB

CHANGELOG.md

File metadata and controls

80 lines (61 loc) · 3.2 KB

Changelog

All notable changes to ExUnitOpenAPI will be documented in this file.

[0.1.0] - 2026-01-22

Initial Release - MVP

First working version of ExUnitOpenAPI. Generates OpenAPI 3.0.3 specifications from Phoenix controller tests with zero annotations required.

Features

  • Telemetry-based capture: Automatically hooks into [:phoenix, :router_dispatch, :stop] events to capture HTTP request/response data during test runs
  • Router analysis: Parses Phoenix router's __routes__/0 to extract path patterns and match requests to route definitions
  • Type inference: Infers JSON Schema types from actual request/response data:
    • Primitives: string, integer, number, boolean, null
    • Objects with nested properties
    • Arrays with item schemas
    • Format detection: uuid, date, date-time, email, uri
  • Path parameters: Extracts from router patterns (:id → {id} in OpenAPI format)
  • Query parameters: Captured from request data
  • Request body schemas: Generated for POST/PUT/PATCH requests
  • Response schemas: Inferred from JSON response bodies
  • Multiple response codes: Documents all status codes observed in tests (200, 404, 422, etc.)
  • Controller-based tags: Auto-generates tags from controller names (UserController → "User")
  • Merge with existing: Preserves manual edits when regenerating spec
  • Mix task: mix openapi.generate runs tests and generates spec
  • Configuration: Router, output path, format, info section, servers, security schemes

Known Limitations

  • No $ref schema deduplication (schemas are inlined, making large specs)
  • No automatic descriptions (only generic ones like "Successful response")
  • No example values in schemas
  • No YAML output (JSON only)
  • Test coverage = documentation coverage (untested endpoints won't appear)

Bug Fixes During Development

  • Handle Plug.Conn.Unfetched structs in path/query/body params
  • Handle iolist response bodies (Phoenix uses these instead of plain strings)
  • Use [:phoenix, :router_dispatch, :stop] telemetry event (not [:phoenix, :endpoint, :stop])
  • Use duck-typing for conn pattern matching (Plug is test-only dependency)

Roadmap

Phase 2 (v0.2.0) - Enhanced Type Inference

  • Schema deduplication with $ref
  • Component schema generation
  • Enum inference from repeated string values
  • Nullable field detection

Phase 3 (v0.3.0) - Developer Experience

  • Optional test metadata for descriptions/tags
  • YAML output format
  • Diff mode (show changes between runs)
  • Merge with existing spec (basic - done in 0.1.0)

Phase 4 (v1.0.0) - Production Ready

  • Request validation mode
  • Coverage reporting (which endpoints lack tests)
  • Multi-spec support (separate specs for API versions)
  • CI integration helpers

Testing Status

Library Tests

  • 108 tests passing
  • Unit tests: TypeInferrer, RouterAnalyzer, Collector, Generator, Config
  • Integration tests: End-to-end flow, telemetry capture
  • Regression tests: Bug fixes for iolist, unfetched params, telemetry event

Integration Testing

  • Tested against personal project
  • Generated spec for 16 endpoints from 50 API controller tests
  • Validated output in Swagger Editor