feat: generate OpenAPI from route manifest

[miclle]

Summary

Adds route manifest mode so fox-openapi can generate contracts from a pre-exported Fox route registry instead of requiring business projects to create OpenAPI-only engine branches.

Changes

• Add --route-manifest CLI/config support and manifest pipeline generation.
• Resolve normal handler input/result types from source using --workdir; keep closure inline types as manifest fallback.
• Preserve status/render wrapper inference so response schemas expose real wire payloads.
• Add structured manifest generic typeArgs support to avoid relying on generic type-name strings for CLI-resolved types.
• Auto-discover standard Load(string) (*Config, error) config loaders for config-taking entries.
• Document the manifest workflow in English and Chinese READMEs.

Verification

• go test ./...
• go run ./cmd/fox-openapi generate --route-manifest /tmp/aone-routes-typed.manifest.json --workdir /Users/miclle/github/aonesuite/infra --out /tmp/aone-openapi-generate.yaml --title 'AoneSuite Infra API'
• go run ./cmd/fox-openapi --route-manifest /tmp/aone-routes-typed.manifest.json --workdir /Users/miclle/github/aonesuite/infra --out /tmp/aone-openapi-root.yaml --title 'AoneSuite Infra API'
• cmp -s /tmp/aone-openapi-generate.yaml /tmp/aone-openapi-root.yaml

[gemini-code-assist]

Code Review

This pull request introduces a "Manifest mode" to fox-openapi, enabling the generation of OpenAPI documents from a pre-exported route manifest file instead of a live application entry. The changes include new CLI flags, updated configuration logic, and a comprehensive type resolution system to map Go types from manifests to OpenAPI schemas. Additionally, the tool now supports automatic discovery of configuration loaders when a standard Load function exists in the config package. Review feedback suggests optimizing memory usage by reducing package loading modes and cautions against fragile string parsing for type identification and name resolution.

I am having trouble creating individual review comments. Click here to see my feedback.

internal/cli/manifest_types.go (78)

The packages.NeedSyntax and packages.NeedTypesInfo modes are not required for resolving handler signatures and types in this file. Removing them can significantly reduce memory usage and speed up package loading, especially in large projects.

cfg := &packages.Config{Dir: r.workdir, Mode: packages.NeedName | packages.NeedTypes}

internal/cli/manifest_types.go (255)

Using fmt.Sprintf('%T', typ) to determine the type kind is fragile as it relies on the internal string representation of go/types implementations. To avoid fragile string parsing, consider using type switches or a more robust way to identify the kind, such as representing composite data with distinct fields.

References

1. To avoid fragile string parsing, represent composite data using a struct with distinct fields rather than a single formatted string.

openapi.go (450-478)

The manifestShortTypeName function and its helpers implement a custom parser for Go type strings. To avoid fragile string parsing, consider if a more formal parsing approach or representing the data using a struct with distinct fields would be safer to avoid potential issues with malformed type strings.

References

1. To avoid fragile string parsing, represent composite data using a struct with distinct fields rather than a single formatted string.

[miclle]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces "Manifest mode" to fox-openapi, allowing the tool to generate OpenAPI documentation from a pre-exported route manifest file instead of executing the application's entry point. It includes significant updates to the CLI configuration, a new pipeline for manifest processing, and logic to resolve Go types for manifest-defined handlers. Additionally, the PR implements automatic discovery of configuration loaders when a standard Load function is present in the config package. Feedback from the review focuses on improving the robustness of handler symbol parsing to avoid false positives with closures, ensuring correct handling of type aliases using types.Unalias, and refining the representation of type identities in the manifest to prevent collisions.

[miclle]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a Manifest mode to fox-openapi, allowing OpenAPI generation from a pre-exported route manifest file. It adds the RouteManifest data structure, CLI support, and logic to resolve Go types from handler symbols. The PR also enhances configuration loader auto-discovery. Review feedback recommends optimizing package loading via batching, utilizing the tool's internal warning system instead of stderr, deduplicating handler cleaning logic, and implementing specialized handling for []byte types in the manifest generator to maintain consistency.

[miclle]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces "Manifest mode" to fox-openapi, enabling OpenAPI document generation from a route manifest file without executing the application entry point. Key changes include a new type resolution system using go/types to extract Go type information from handler symbols and an enhanced configuration loader that automatically discovers package-level Load functions. Review feedback identifies an opportunity to improve schema naming by populating the String field in RouteManifestType during type resolution, which prevents potential name collisions for anonymous or unnamed types.

[miclle]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a 'Manifest mode' to fox-openapi, allowing OpenAPI specifications to be generated from a pre-exported route manifest file instead of a live application entry. It adds the --route-manifest flag, updates configuration handling, and implements logic to resolve Go types and signatures from manifest data. The PR also enhances entry configuration by automatically discovering package-level Load functions. Review feedback suggests improving the reliability of Go package resolution by including imports and dependencies in the loader configuration and recommends replacing fragile string parsing of Go symbols and generic type names with more structured data representations.

[miclle]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a 'Manifest mode' for fox-openapi, allowing it to generate OpenAPI documentation from a pre-exported route manifest file instead of requiring a live application entry. The changes include adding manifest-related types, logic for resolving types from handler symbols, and updating the CLI to support the new --route-manifest flag. The reviewer correctly identified that the string parsing logic in parseRuntimeHandlerSymbol is fragile and recommended using a structured approach for handling composite symbols, which is a valid improvement opportunity.

[miclle]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces "Manifest Mode" to fox-openapi, enabling OpenAPI specification generation from a pre-exported route manifest file instead of executing the application entry point. The implementation includes new CLI flags, documentation, and logic to resolve Go types from manifest handler symbols. Additionally, it adds automatic discovery for configuration loaders when an entry function requires a config and a path is provided. Review feedback suggested propagating the IncludeTestFiles setting into the manifest type resolution logic to ensure handlers defined in test files are correctly resolved when requested.

[miclle]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a 'Manifest mode' to fox-openapi, allowing OpenAPI document generation from a route manifest file exported by a Fox application to avoid running the application entry. It also adds automatic discovery of configuration loaders when an entry configuration path is provided. Review feedback identifies a missing fallback for OperationID in manifest mode when handler symbols are absent and notes a limitation in resolving generic type arguments during manifest-based type enrichment.

[miclle]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a 'Manifest mode' for the fox-openapi tool, allowing it to generate OpenAPI documents from a route manifest file instead of requiring a live application entry. This includes new types for manifest representation, logic to enrich manifest types from source code, and updates to the CLI to support the new --route-manifest flag. My feedback highlights the need to refactor the significant code duplication between the new manifest-based generation logic and the existing reflection-based logic, as well as a recommendation to replace manual string parsing in route_manifest.go with structured data types to improve robustness.

[miclle]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a 'Manifest mode' for fox-openapi, enabling OpenAPI document generation from a pre-exported route manifest file. This feature decouples documentation generation from application execution, providing greater flexibility. The changes include updates to the CLI, configuration management, type resolution logic, and the core OpenAPI generator. I have no feedback to provide on these changes.