mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-17 19:55:34 +00:00
Lunny Xiao
4e38ace168
Closes #37. Gitea generates an OpenAPI 3.0 document since 1.27 (`templates/swagger/v1_openapi3_json.tmpl`, renamed to `templates/swagger/v1-openapi3.generated.json` on main, served by an instance at `/openapi3.v1.json`), but this site never picked it up and still published Swagger 2.0 only. That is what the issue is about: code generators such as `openapi-python-client` reject the document with "You may be trying to use a Swagger document; this is not supported by this project". **What this does** - `update_api_docs.sh` downloads the OpenAPI 3.0 document next to the Swagger 2.0 one, rewrites the same placeholders (they sit in `servers` instead of `basePath`) and writes `static/openapi3-latest.json` and `static/openapi3-<minor>.json`. Versions that do not have one (1.26 and older) are skipped with a message and keep their Swagger 2.0 document. - The OpenAPI 3.0 document is rendered where it exists (`/api/` and `/api/next/`), the older versions keep rendering Swagger 2.0. Both documents describe the same api and carry the same operation ids, so no url of an operation page changes; the `basePath` normalization is now only applied to the Swagger 2.0 documents, since a full url in `servers` is valid. - The overview page of each version links both documents for download, which is what the issue actually needs: `https://docs.gitea.com/openapi3-27.json` for the current release, `https://docs.gitea.com/openapi3-latest.json` for gitea main. - The scheduled workflow now refreshes and proposes both documents of gitea main. **Verification** - `pnpm dlx @redocly/cli lint static/openapi3-latest.json`: valid, only content warnings that come from upstream (missing 4xx responses, ambiguous paths). - `openapi-python-client generate --path static/openapi3-latest.json`, the tool from the issue, generates a client. The only warning left is `POST /markdown/raw`, whose request body is `text/plain`. - Operation ids of `static/swagger-27.json` and `static/openapi3-27.json` are identical (481 on both sides), so the operation pages keep their urls. - Built the api product and compared a rendered operation page against the Swagger 2.0 one: same sections, the request body is now marked required where the document says so. The released Swagger 2.0 documents are kept: they are the only description 1.26 and older ever produced, and some tooling still expects them. <!-- cloudflare-preview --> Preview: https://pr-514.docs-gitea-com.pages.dev Reviewed-on: https://gitea.com/gitea/docs/pulls/514 Reviewed-by: bircni <[email protected]>
91 lines
2.5 KiB
Makefile
91 lines
2.5 KiB
Makefile
GITEA_AWESOME_REMOTE := https://gitea.com/gitea/awesome-gitea.git
|
|
GITEA_AWESOME_BRANCH := main
|
|
|
|
.PHONY: all
|
|
all: build
|
|
|
|
.PHONY: create_dir
|
|
create_dir:
|
|
mkdir -p .tmp
|
|
|
|
.PHONY: clone_awesome
|
|
clone_awesome: create_dir
|
|
git clone --branch=$(GITEA_AWESOME_BRANCH) $(GITEA_AWESOME_REMOTE) .tmp/upstream-awesome || true
|
|
|
|
.PHONY: prepare-awesome-latest
|
|
prepare-awesome-latest: clone_awesome
|
|
cp .tmp/upstream-awesome/README.md docs/awesome.md
|
|
|
|
.PHONY: prepare-awesome\#%
|
|
prepare-awesome\#%:
|
|
cp .tmp/upstream-awesome/README.md versioned_docs/version-1.$*/awesome.md
|
|
|
|
.PHONY: install
|
|
install:
|
|
pnpm install
|
|
|
|
.PHONY: prepare-docs
|
|
prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27
|
|
|
|
.PHONY: build
|
|
build:
|
|
pnpm run build
|
|
|
|
# type checks the astro site and its components
|
|
.PHONY: check
|
|
check:
|
|
pnpm run check
|
|
|
|
.PHONY: serve
|
|
serve: prepare-docs
|
|
pnpm run dev
|
|
|
|
# only the english docs of the version served at the root, plus the runner:
|
|
# starts in a few seconds instead of loading the whole matrix
|
|
.PHONY: serve-fast
|
|
serve-fast:
|
|
pnpm run dev:en-latest
|
|
|
|
# search is built by pagefind at build time, so it is only available on the
|
|
# built site; this serves it locally
|
|
.PHONY: serve-built
|
|
serve-built: build
|
|
pnpm run preview
|
|
|
|
.PHONY: clean
|
|
clean:
|
|
rm -rf .tmp
|
|
rm -rf sites/docs/dist
|
|
rm -rf sites/docs/.cache
|
|
rm -rf sites/docs/node_modules/.astro
|
|
|
|
# static/swagger-*.json and static/openapi3-*.json are committed files, use
|
|
# update-api-docs to refresh them
|
|
.PHONY: update-api-docs
|
|
update-api-docs:
|
|
./update_api_docs.sh
|
|
|
|
# only refresh the documents of the gitea main branch (used by the cron job)
|
|
.PHONY: update-api-docs-latest
|
|
update-api-docs-latest:
|
|
./update_api_docs.sh --latest-only
|
|
|
|
# regenerate the generated runner reference pages of the develop docs from the
|
|
# main branch of gitea/runner (used by the update runner reference cron job)
|
|
.PHONY: update-runner-docs
|
|
update-runner-docs:
|
|
./update_runner_docs.sh main runner-docs/reference
|
|
|
|
# same, for every documented release series: the tags are looked up through the
|
|
# Gitea API, so a runner release needs no change here
|
|
.PHONY: update-runner-docs-released
|
|
update-runner-docs-released:
|
|
./update_runner_docs.sh --released
|
|
|
|
# freezes the current docs or runner tree as a new version, see
|
|
# scripts/cut-version.mjs
|
|
.PHONY: cut-version
|
|
cut-version:
|
|
@test -n "$(PRODUCT)" -a -n "$(VERSION)" || { echo 'usage: make cut-version PRODUCT=docs VERSION=1.28'; exit 1; }
|
|
node scripts/cut-version.mjs $(PRODUCT) $(VERSION)
|