openapi-extractor

openapi-extractor is a Nextcloud-maintained CLI tool that statically parses PHP controller classes and their PHPDoc/attribute annotations to produce OpenAPI 3.x specifications, so app and server developers never have to hand-write or manually sync API docs.

It ships as a composer dev-dependency with two binaries — generate-spec, which walks an app’s controllers and OCS routes to emit a spec, and merge-specs, which combines per-app specs into a unified document. It is wired into Nextcloud’s CI via a reusable GitHub Actions workflow template so pull requests fail if the checked-in spec drifts from the annotated source.

What You Get

• A generate-spec CLI binary that scans controller classes and OCS routes for a Nextcloud app or the server itself
• A merge-specs binary for combining multiple per-app OpenAPI documents into one consolidated spec
• Support for PHP 8 attributes and PHPDoc annotations to describe parameters, responses, and status codes
• A reusable GitHub Actions workflow template for enforcing that committed specs stay in sync with source
• Structured error and warning logging (via its Logger/LoggerLevel classes) pinpointing exactly which controller method is malformed

Common Use Cases

• Generating an OpenAPI spec for a Nextcloud app during development so it can be committed alongside the code
• Enforcing spec freshness in CI by regenerating and diffing against the checked-in openapi.json on every pull request
• Merging the OpenAPI documents of multiple installed apps into a single spec for API tooling or documentation sites
• Auditing controller annotations for missing or inconsistent OpenAPI metadata before a release

Under The Hood

Architecture — The tool is a static analyzer built around PHP-Parser: generate-spec.php walks a Nextcloud app’s controller directory, builds an AST for each class, and Route.php/ControllerMethod.php extract HTTP method, path, parameters, and response metadata from PHP attributes and PHPDoc comments; OpenApiType.php converts PHP type declarations into OpenAPI schema fragments, and the results are serialized to JSON via Helpers.php. merge-specs.php performs a second, simpler pass that loads multiple already-generated JSON documents and deep-merges their paths/components sections. Tech Stack — Pure PHP 8.1+ using nikic/php-parser for AST parsing, phpstan/phpdoc-parser for docblock parsing, and adhocore/cli for the command-line interface; nextcloud/coding-standard and rector enforce style and modernize the codebase in CI. Code Quality — The codebase is modest (~2,200 lines across ~13 classes) with clear single-responsibility classes (Route, ControllerMethod, ControllerMethodParameter, ControllerMethodResponse) and a dedicated Logger/LoggerLevel pair for structured diagnostics; tests run against fixture Nextcloud apps under tests/ and assert generated specs match committed JSON snapshots (openapi-full.json, openapi-federation.json, etc.) rather than using traditional unit assertions. API Design — The public surface is intentionally thin: two CLI binaries with minimal flags, so nearly all configuration happens through PHP attributes/PHPDoc on the consuming app’s own controllers, keeping the tool’s own API footprint small but requiring familiarity with Nextcloud’s specific annotation conventions.