feat(openapi): compile-time specs and scaffolding tools#624
Conversation
Summary of ChangesHello @pitabwire, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the 'Frame' framework by integrating compile-time OpenAPI specification serving and introducing powerful scaffolding tools. The changes enable developers to automatically generate and embed OpenAPI documentation, ensuring API contracts are always up-to-date and served efficiently. Additionally, a new blueprint merging system provides flexible and safe configuration management, particularly beneficial for AI-assisted development, alongside tools for setting up monorepo projects with ease. These additions streamline development workflows and improve the maintainability and discoverability of services. Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
There is a problem with the Gemini CLI PR review. Please check the action logs for details. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces significant new features: compile-time OpenAPI specification handling and scaffolding tools for new projects. The OpenAPI implementation is robust, using compile-time embedding for performance and predictability. The new blueprint merge semantics with additive defaults and explicit overrides are well-defined and tested. The documentation updates are comprehensive and clearly explain the new monorepo structure and tooling.
I've found a few issues in the new scaffolding tools. One is a high-severity bug in frame-init that generates broken code for the monolith entrypoint. Another is a medium-severity issue in frame-openapi that unnecessarily restricts path generation for go:generate directives. I've also pointed out some dead code in the blueprint merge logic.
Overall, this is a great addition to the framework. Addressing the issues in the tooling will make them much more reliable for developers.
tools/cmd/frame-init/main.go
Outdated
| func writeMonolithEntry(root string, services []string) error { | ||
| path := filepath.Join(root, "cmd", "monolith", "main.go") | ||
| if exists(path) { | ||
| return nil | ||
| } | ||
| if err := ensureDir(filepath.Join(root, "cmd", "monolith")); err != nil { | ||
| return err | ||
| } | ||
|
|
||
| imports := []string{"\"log\"", "\"net/http\"", "\"github.com/pitabwire/frame\""} | ||
| for _, svc := range services { | ||
| imports = append(imports, fmt.Sprintf("\"%s/apps/%s/service\"", "your/module", svc)) | ||
| } | ||
|
|
||
| var builders strings.Builder | ||
| builders.WriteString("package main\n\nimport (\n") | ||
| for _, imp := range imports { | ||
| builders.WriteString("\t" + imp + "\n") | ||
| } | ||
| builders.WriteString(")\n\nfunc main() {\n\tmux := http.NewServeMux()\n") | ||
| for _, svc := range services { | ||
| builders.WriteString(fmt.Sprintf("\t%s.RegisterRoutes(mux)\n", svc)) | ||
| } | ||
| builders.WriteString("\tctx, svc := frame.NewService(\n\t\tframe.WithName(\"monolith\"),\n\t\tframe.WithHTTPHandler(mux),\n\t)\n\tif err := svc.Run(ctx, \":8080\"); err != nil {\n\t\tlog.Fatal(err)\n\t}\n}\n") | ||
|
|
||
| return os.WriteFile(path, []byte(builders.String()), 0o644) | ||
| } |
There was a problem hiding this comment.
Resolved: module is now required when services are provided, monolith imports use proper aliases derived from service names, and the entrypoint is generated with those aliases.
blueprint/merge.go
Outdated
| type mergeConfig[T any] struct { | ||
| key keyFunc[T] | ||
| replace replaceFunc[T] | ||
| override flagFunc[T] | ||
| remove flagFunc[T] | ||
| } |
There was a problem hiding this comment.
Resolved: removed unused mergeConfig struct and refactored merge helpers for clarity.
| func relPath(base, target string) (string, bool) { | ||
| rel, err := filepath.Rel(base, target) | ||
| if err != nil { | ||
| return "", false | ||
| } | ||
| if strings.HasPrefix(rel, "..") { | ||
| return "", false | ||
| } | ||
| return rel, true | ||
| } |
There was a problem hiding this comment.
Resolved: relPath now allows .. so go:generate works with sibling proto/pkg layouts.
1 participant
Summary
tools/to auto-generate specs and embed helper/pkgconventionTesting
go test ./...