Serve OpenAPI 3.0 spec at /openapi.v1.json#37038
Conversation
Add a build-time conversion step that transforms the existing Swagger 2.0 spec into an OpenAPI 3.0 spec. The OAS3 spec is served alongside the existing Swagger 2.0 spec, enabling API clients that require OAS3 (progenitor, openapi-python-client, etc.) to generate code directly from Gitea's API. New files: - build/generate-openapi.go — converts swagger v1_json.tmpl to OAS3 - build/openapi3-tools.go — tool dependency for kin-openapi - routers/web/swagger_json.go — serves the OAS3 spec - templates/swagger/v1_openapi3_json.tmpl — generated OAS3 spec
GiteaBot
added
the
lgtm/need 2
github-actions
bot
added
modifies/go
|
Can you add more comments and document more details in the tool's code? For example: why it needs |
| printf "%s" "$${diff}"; \ | ||
| exit 1; \ | ||
| fi | ||
|
|
There was a problem hiding this comment.
Remove the 3 in target and variable names as well as templates/swagger/v1_openapi3_json.tmpl. We don't specify a swagger version either so this is consistent and simpler.
|
I think we should probably also evaluate using OAS3 for swagger-ui. Long-term I would like us to move completely to a OAS3-based solution, ideally OAS 3.1. |
There was a problem hiding this comment.
Pull request overview
Adds an OpenAPI 3.0 (OAS3) JSON spec endpoint generated at build-time by converting the existing Swagger 2.0 template, so API clients that require OAS3 can generate SDKs directly while keeping the existing Swagger v1 spec.
Changes:
- Serve an OAS3 spec at
/openapi.v1.jsonalongside the existing/swagger.v1.json. - Add a generator (
build/generate-openapi.go) to converttemplates/swagger/v1_json.tmpl→templates/swagger/v1_openapi3_json.tmpl. - Wire generation + consistency checks into
make generate-swagger/ backend checks and add required Go module dependencies.
Reviewed changes
Copilot reviewed 7 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| routers/web/web.go | Registers the new /openapi.v1.json route when Swagger is enabled. |
| routers/web/swagger_json.go | Adds the OpenAPI3Json handler to render the OAS3 JSON template. |
| build/generate-openapi.go | Implements Swagger2→OAS3 conversion and post-processing/enrichment steps. |
| build/openapi3-tools.go | Attempts to pin kin-openapi tool deps for generation. |
| templates/swagger/v1_openapi3_json.tmpl | Generated OAS3 JSON template served by the new route. |
| Makefile | Adds OpenAPI3 generation/check targets and hooks into existing checks. |
| go.mod / go.sum | Adds kin-openapi and related transitive deps. |
| .editorconfig | Adds formatting rules for the generated OAS3 template. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| .PHONY: generate-openapi3 | ||
| generate-openapi3: $(OPENAPI3_SPEC) ## generate the OpenAPI 3.0 spec from the Swagger 2.0 spec | ||
|
|
||
| $(OPENAPI3_SPEC): $(SWAGGER_SPEC) |
There was a problem hiding this comment.
The $(OPENAPI3_SPEC) rule only depends on $(SWAGGER_SPEC). If build/generate-openapi.go changes, make generate-openapi3 can become a no-op (stale v1_openapi3_json.tmpl) because Make doesn't know the generator changed. Add build/generate-openapi.go (and any other inputs like build/openapi3-tools.go) as prerequisites so the OpenAPI3 template is regenerated whenever the generator changes.
| $(OPENAPI3_SPEC): $(SWAGGER_SPEC) | |
| $(OPENAPI3_SPEC): $(SWAGGER_SPEC) build/generate-openapi.go |
|
|
||
| _ = key |
There was a problem hiding this comment.
There is a leftover no-op statement (_ = key) at the end of the for key, usages := range enumGroups loop. Since key is already used by the loop header, this line is unnecessary and should be removed to keep the generator clean.
| _ = key |
| //go:build tools | ||
|
|
||
| package build | ||
|
|
||
| // This blank import ensures kin-openapi stays in go.mod for use by | ||
| // build/generate-openapi.go (which has //go:build ignore). | ||
| import ( | ||
| _ "github.com/getkin/kin-openapi/openapi2" | ||
| _ "github.com/getkin/kin-openapi/openapi2conv" | ||
| _ "github.com/getkin/kin-openapi/openapi3" |
There was a problem hiding this comment.
build/openapi3-tools.go is behind //go:build tools, but make tidy runs go mod tidy without -tags tools (Makefile:447-450). That means kin-openapi will be considered unused and removed, and later go run build/generate-openapi.go may re-add/modify go.mod/go.sum or fail in CI. To make this stable, either remove the tools build tag from this deps file (so tidy sees the blank imports), or update the tidy target/CI to run go mod tidy -tags tools (and keep this file under that tag).
IMO this should be one step. Displaying spec that's converted from generated one does not feel right to me. It's a step too much in the pipeline and I'd prefer to be closer to what we directly control. I'll try to get back to generating API directly from structs after I'll finish dealing with my package related PRs as I'm tied up there a bit. |
|
BTW I would make it just |
|
what about v4 which is supposedly in works? |
|
No idea about that , but I don't think anyone wants to maintain multiple versions of the api existing at the same time in the same repo, that's more like wishful thinking. |
|
But I guess keep the v1 for consistency with swagger and the unlikely event that there will be v2+. |
|
Regarding
|
Add a build-time conversion step that transforms the existing Swagger 2.0 spec into an OpenAPI 3.0 spec. The OAS3 spec is served alongside the existing Swagger 2.0 spec, enabling API clients that require OAS3 (progenitor, openapi-python-client, etc.) to generate code directly from Gitea's API.
New files:
This is not to be an answer to how gitea handles OAS3 long term, but a way to use what we have to move a step forward.
See https://github.com/myers/gt for how this can be used.
Written with Claude Code using Opus, and human reviewed.