Openapi Introspector Laravel Package

Getting Started

Install with composer require dermanomann/openapi-introspector and publish any package config if the service provider exposes one. Start by looking at the package’s attribute classes and the introspection command/route it registers, then annotate a single controller action with the package’s OpenAPI attributes. Generate the spec and inspect the output before rolling it across the API. The first practical use case is documenting an existing Laravel route without rewriting it: keep your route definitions, add attributes to the controller methods, and let the package merge route metadata into the OpenAPI output.

Implementation Patterns

• Hybrid mode: Use hybrid mode when you want existing classic/hand-written OpenAPI operations to remain alongside route-derived operations. In 1.0.1, classic operations are preserved in hybrid mode rather than being replaced by route introspection.
• Attribute-backed routes: Put OpenAPI attributes on controller methods and define route path parameters normally in Laravel. The package maps route path parameters onto the attribute placeholders by position, so /users/{user} maps to the first {...} placeholder in the attribute path.
• Collision handling: If a documented operation and a route describe the same path/method, prefer documenting the route once. In 1.0.1, documented operations are kept when routes collide with them, which lets you hand-tune an operation while still using route introspection elsewhere.
• Server URL prefixes: If your OpenAPI server URL includes a base path such as https://api.example.com/v1, the package strips that prefix from route paths during introspection. Define server URLs at the document level and let route paths stay relative.
• CI generation: Run spec generation as a build step and diff the generated OpenAPI file so attribute/route changes are reviewed like code.

Gotchas and Tips

• Positional placeholder mapping is brittle: Route parameter names do not need to match attribute placeholder names, but the order must. Keep route parameter order and attribute placeholder order aligned, and add tests around paths with multiple parameters.
• Hybrid mode can surprise you: Classic operations are preserved, but route-derived operations may still collide. Use explicit operation IDs and paths to avoid ambiguous merges.
• Collisions are resolved in favour of documented operations in 1.0.1: If a route unexpectedly disappears from the generated spec, check whether a documented operation with the same path/method is taking precedence.
• Server URL prefix stripping: If generated paths look wrong, check the configured servers URL. A server URL with a path prefix will be removed from route paths; a trailing slash or missing prefix can change the result.
• Cache and route discovery: Laravel route caching can affect introspection if the package relies on route registration. Generate specs in an environment where routes are discoverable, and avoid stale route caches in CI.
• Debugging: Start with a minimal controller/action and one route, inspect the generated operation, then add parameters, middleware, and server URLs incrementally. Most issues will be route-to-attribute path mismatches or collision handling rather than OpenAPI schema problems.