Serve OpenAPI 3.0 spec at /openapi.v1.json

[myers]

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

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.

[wxiaoguang]

Can you add more comments and document more details in the tool's code? For example: why it needs knownEnumTypes mapping? etc.

[silverwind]

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.

[Copilot]

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.json alongside the existing /swagger.v1.json.
• Add a generator (build/generate-openapi.go) to convert templates/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.

[TheFox0x7]

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.

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.

[silverwind]

BTW I would make it just openapi.json, there will never be a v2, the naming of the swagger file is legacy but should be kept.

[TheFox0x7]

what about v4 which is supposedly in works?

[silverwind]

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.

[silverwind]

But I guess keep the v1 for consistency with swagger and the unlikely event that there will be v2+.

[silverwind]

Regarding knownEnumTypes two better ideas:

1. Create a small AST walker to extract the enums
2. Leave the enums as-is, e.g. inline

[myers]

Regarding knownEnumTypes two better ideas:

1. Create a small AST walker to extract the enums

2. Leave the enums as-is, e.g. inline

SDK generators like progenitor (Rust) need named enum types to produce good code. Without them, you get duplicate anonymous string types on every field instead of a shared StateType enum. Deduplicating enums and giving them proper names in #/components/schemas/ is the main motivation for the converter.

AST Walker: Walk Go source to find type StateType string declarations and extract the real type names. This would eliminate the map entirely and be correct by construction. But it's a significant scope increase — needs to parse Go source files, resolve which types are actually used in swagger-annotated structs, and handle edge cases.

Worth doing eventually but feels like a separate PR.

Or maybe better to focus efforts on building a better go annotations to OpenAPI 3 spec.

My goal here was the shortest path to being able to use OpenAPI ecosystem tools.

[myers]

IMO this should be one step. Displaying spec that's converted from generated one does not feel right to me. I

I understand the concern — a two-stage pipeline (annotations → Swagger 2.0 → OAS3) is more steps than ideal. But I think this PR is a useful incremental step:

1. It helps now — SDK generators and tooling that require OAS3 can consume Gitea's API today, without waiting for a better tool.
2. It doesn't block the direct approach — when someone builds direct OAS3 generation from structs, this converter simply gets deleted. No tech debt accumulates because the converter is a standalone build tool with no runtime footprint
3. The conversion is build-time only — the generated spec is committed as a template, so there's no runtime overhead or dependency on kin-openapi in the Gitea binary

That said, direct OAS3 generation would be strictly better long-term.

[myers]

@silverwind @TheFox0x7 I made some changes. Could we move forward with this?

If we don't want to move forward with this can you give me a path to get an openapi 3.x spec that you do like?

[TheFox0x7]

Could we move forward with this?

Have you addressed reviews?

[myers]

Could we move forward with this?

Have you addressed reviews?

I had missed some, thank you for the prompt.

[silverwind]

Reviewed with Claude Opus 4.7 and opencode; aggregated findings below.

High

H1. Missing reserved username entry — routers/web/web.go:1746 + models/user/user.go:586-623

swagger.v1.json is in reservedUsernames at line 619; openapi.v1.json is not. Since /{username} is a catch-all, a user registered with name openapi.v1.json would shadow the new route. Add the string to reservedUsernames (and consider extending the TestRenameReservedUsername cases at tests/integration/user_test.go:172).

Medium

M1. addDeprecatedFlags substring match — build/generate-openapi.go:193

strings.Contains(desc, "deprecated") will false-positive on phrases like "not deprecated" or "previously deprecated, now supported". A word-boundary regex or a stricter check would be safer. Current Gitea descriptions appear safe, but the rule is fragile for future additions.

M2. fixFileSchemas only traverses one level — build/generate-openapi.go:105-129

Walks response/request-body media-types but doesn't recurse into schema.Properties, schema.Items, allOf/oneOf. Current output contains zero "type": "file" so the PR is fine today — just worth a recursive walker if this stays long-term.

M3. knownEnumTypes is a hand-maintained allowlist — build/generate-openapi.go:307-314

Already discussed — author chose this over an AST walker as the shorter path. Worth documenting that this map must be updated when new enum types are added, otherwise new enums will silently get derived generic names. openapi3-check in CI will catch drift, so acceptable as-is.

Low

L1. Makefile prereq omits tools file — Makefile:263

$(OPENAPI3_SPEC): $(SWAGGER_SPEC) build/generate-openapi.go — if build/openapi3-tools.go changes (dep versions), regeneration isn't triggered. Cosmetic.

L2. package build + //go:build tools — build/openapi3-tools.go:6

All other files in build/ are package main with //go:build ignore. Works fine (author verified tidy-check passes on Go ≥1.17), just an outlier package layout.

L3. Naming inconsistency — Makefile variables/targets vs. URL path

URL /openapi.v1.json has no 3; template filename v1_openapi3_json.tmpl and Makefile vars/targets do. Pick one — minor.

L4. deriveEnumName fallback appends "Enum" — build/generate-openapi.go:373

When no x-go-enum-desc extension exists, schemas get generic names like StatusEnum. Benign; just flagging so reviewers understand when a generic name appears.

---

Posted by Claude Opus 4.7 on behalf of @silverwind.

[silverwind]

Regarding knownEnumTypes I'm still not quite happy. Ideas from Claude:

Better designs, ranked:

1. Annotate the Go enum types themselves (e.g. // swagger:enum-type StateType comment → emitted as x-go-enum-type extension) so this converter reads the type name directly. Kills the map, zero future maintenance. Needs swagger-gen support though.
2. AST walker — correct by construction but ~150 LOC and a separate Go-parsing pass. Bigger change for marginal gain.
3. Fail loudly on unknown prefixes in strict mode, so CI breaks instead of silently producing FooEnum.

[silverwind]

Still think these targets should not have a version, e.g. generate-openapi.

[myers]

swagger == openapi 2.0, so something labeled only openapi could be v2 or v3. The version number makes it clear

[silverwind]

I never heard about openapi 2.0, and we don't want to rename this make target once we switch to openapi 3.1, 3.2 or 4.0. there will only ever be one openapi output.

[myers]

The project already have a OpenAPI spec: the swagger spec. Swagger became OpenAPI 2.0, then OpenAPI came out with a new version, 3.0. If we rename the OpenAPI 3.0 spec "openapi", then it will be unclear what version this end point is.

[wxiaoguang]

I think generate-openapi3 is a right name

[TheFox0x7]

?
If we're being pedantic it should be generate-openapi2. Swagger has no version, It's the same as openapi2.
Besides I really don't follow here... what integrations? Who's dependent on gitea Makefile or integrating with it? Why would you even promise that makefile is stable, especially for something that's embedded in code and does not need to be generated by any end user or packager?

[wxiaoguang]

If we upgrade to 3.1, should we rename to generate-openapi31 breaking existing integrations?

Why? 3.1 literally belongs to 3, right? 4 doesn't belong to 3 and it breaks from 3, right?

So generate-openapi3 is absolutely the right name

[silverwind]

OAS 3.1 is not strictly backwards-compatible with 3.0, there are subtle breaking changes. I don't get this discussion, we have a "swagger spec" and we have a "openapi spec", versions are irrelevant in both for the generation purpose. I would not recommend to have v3 and v4 specs to co-exist.

[wxiaoguang]

I would not recommend to have v3 and v4 specs to co-exist.

But now v2 (swagger) and and v3 do co-exist.

I do not see anything wrong with the name "openapi3".

If "OAS 3.1 is not strictly backwards-compatible with 3.0", then "openapi3" is just even better.

Why you prefer to mix unclear things together? What's wrong with the number "3" to end users? Who will be hurt or confused?

[TheFox0x7]

OAS 3.1 is not strictly backwards-compatible with 3.0, there are subtle breaking changes

Then why have it as openapi3.v1.json in the router? If in the future we swap it to 3.1 then "the subtle breaking changes" will impact users. Should THAT be more of an issue than makefile?
The target could be named anything and it wouldn't make a difference since no user will ever run it in the first place.

[TheFox0x7]

it generally looks good and when I plugged it into scalar a bit ago it had no issues.

If we're keeping the version in a route, maybe have the entire one? I'm not sure what changed from 3.0 -> 3.1, but it's currently ambiguous which of the two is served which might be confusing to some people if they make wrong assumption.

[silverwind]

OAS 3.1 is some keyword alignment and full JSON schema support. A very nice upgrade if you actually work with JSON schema. Likely not relevant for gitea.

Long-term I'd like us to switch to a generator that generates OAS 3+ only but I guess this serves as a bridge because that migration will be big.

[TheFox0x7]

good to go from my pov. Ran the output spec through vacuum and it doesn't report anything major that's actionable apart from uniqueItems constraint on some string properties. Nothing major though

[wxiaoguang]

Some TODOs for following up PRs in my mind:

1. Refactor the types: use api.VisibilityModes[form.Visibility] instead of api.VisibilityModes[string(form.Visibility)]
2. Add a link on the UI to tell users the OpenAPI v3 link