Skip to content

Serve OpenAPI 3.0 spec at /openapi.v1.json #37038

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
myers wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Serve OpenAPI 3.0 spec at /openapi.v1.json #37038

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .editorconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ insert_final_newline = false
indent_style = space
insert_final_newline = false

[templates/swagger/v1_openapi3_json.tmpl]
indent_style = space

[templates/user/auth/oidc_wellknown.tmpl]
indent_style = space

Expand Down
20 changes: 18 additions & 2 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,7 @@ ESLINT_CONCURRENCY ?= 2
SWAGGER_SPEC := templates/swagger/v1_json.tmpl
SWAGGER_SPEC_INPUT := templates/swagger/v1_input.json
SWAGGER_EXCLUDE := code.gitea.io/sdk
OPENAPI3_SPEC := templates/swagger/v1_openapi3_json.tmpl

TEST_MYSQL_HOST ?= mysql:3306
TEST_MYSQL_DBNAME ?= testgitea
Expand Down Expand Up @@ -242,7 +243,7 @@ TAGS_PREREQ := $(TAGS_EVIDENCE)
endif

.PHONY: generate-swagger
generate-swagger: $(SWAGGER_SPEC) ## generate the swagger spec from code comments
generate-swagger: $(SWAGGER_SPEC) $(OPENAPI3_SPEC) ## generate the swagger spec from code comments

$(SWAGGER_SPEC): $(GO_SOURCES) $(SWAGGER_SPEC_INPUT)
$(GO) run $(SWAGGER_PACKAGE) generate spec --exclude "$(SWAGGER_EXCLUDE)" --input "$(SWAGGER_SPEC_INPUT)" --output './$(SWAGGER_SPEC)'
Expand All @@ -264,14 +265,29 @@ swagger-validate: ## check if the swagger spec is valid
$(GO) run $(SWAGGER_PACKAGE) validate './$(SWAGGER_SPEC)'
@$(SED_INPLACE) -E -e 's|"basePath":( *)"/(.*)"|"basePath":\1"\2"|g' './$(SWAGGER_SPEC)' # remove the prefix slash from basePath

.PHONY: generate-openapi3
generate-openapi3: $(OPENAPI3_SPEC) ## generate the OpenAPI 3.0 spec from the Swagger 2.0 spec

$(OPENAPI3_SPEC): $(SWAGGER_SPEC)
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
$(OPENAPI3_SPEC): $(SWAGGER_SPEC)
$(OPENAPI3_SPEC): $(SWAGGER_SPEC) build/generate-openapi.go

Copilot uses AI. Check for mistakes.
$(GO) run build/generate-openapi.go

.PHONY: openapi3-check
openapi3-check: generate-openapi3
@diff=$$(git diff --color=always '$(OPENAPI3_SPEC)'); \
if [ -n "$$diff" ]; then \
echo "Please run 'make generate-openapi3' and commit the result:"; \
printf "%s" "$${diff}"; \
exit 1; \
fi

Copy link
Copy Markdown
Member

@silverwind silverwind Mar 30, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

.PHONY: checks
checks: checks-frontend checks-backend ## run various consistency checks

.PHONY: checks-frontend
checks-frontend: lockfile-check svg-check ## check frontend files

.PHONY: checks-backend
checks-backend: tidy-check swagger-check fmt-check swagger-validate security-check ## check backend files
checks-backend: tidy-check swagger-check openapi3-check fmt-check swagger-validate security-check ## check backend files

.PHONY: lint
lint: lint-frontend lint-backend lint-spell ## lint everything
Expand Down
Loading
Loading