feat(api): render and publish the openapi 3.0 documents (#514)

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]>

README.md

@@ -8,7 +8,7 @@ The site covers three products, all served from this repository:
 | Product | Content | Versions | Languages |
 | --- | --- | --- | --- |
 | Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
-| API | `static/swagger-*.json` | next, 1.27 … 1.22 | English |
+| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 1.27 … 1.22 | English |
 | Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English |
 
 The enterprise documentation is built and deployed from its own repository and
@@ -64,16 +64,21 @@ matrix.
 
 ## API docs
 
-The swagger definitions rendered under `/api/` live in
-`static/swagger-latest.json` (gitea main) and `static/swagger-<minor>.json`
-(released versions).
+The definitions rendered under `/api/` live in `static/`:
+`swagger-latest.json` (gitea main) and `swagger-<minor>.json` (released
+versions) hold the swagger 2.0 document every gitea version ships,
+`openapi3-latest.json` and `openapi3-<minor>.json` the openapi 3.0 document
+gitea generates since 1.27. The openapi 3.0 document is what gets rendered
+where it exists, and both are offered for download on the overview page of the
+version, since code generators cannot read the rendered pages (and several of
+them reject swagger 2.0).
 
 ```shell
 make update-api-docs         # refresh latest + every released version
-make update-api-docs-latest  # refresh only static/swagger-latest.json
+make update-api-docs-latest  # refresh only the documents of gitea main
 ```
 
-`static/swagger-latest.json` is refreshed automatically: the `update swagger
+The documents of gitea main are refreshed automatically: the `update api spec
 files` workflow runs every 12 hours and opens a pull request whenever gitea main
 changed. Released versions are updated by hand when a new gitea version is
 documented.