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

packages/content-loader/src/products.ts

@@ -38,8 +38,17 @@ export interface VersionDef {
   banner?: 'unreleased' | 'unmaintained';
   /** Content directories, relative to the repository root, per language. */
   sources: Partial<Record<LocaleId, string>>;
-  /** OpenAPI document, relative to the repository root (api product only). */
+  /**
+   * Swagger 2.0 document, relative to the repository root (api product only).
+   * Every documented gitea version ships one.
+   */
   schema?: string;
+  /**
+   * OpenAPI 3.0 document, relative to the repository root (api product only).
+   * Gitea generates it since 1.27; it is what gets rendered and what the code
+   * generators that rejected the swagger 2.0 document can read.
+   */
+  openapi3?: string;
   variables?: VersionVariables;
 }
 
@@ -239,6 +248,7 @@ const apiProduct: ProductDef = {
       banner: 'unreleased',
       sources: {},
       schema: 'static/swagger-latest.json',
+      openapi3: 'static/openapi3-latest.json',
     },
     {
       id: '1.27',
@@ -247,6 +257,7 @@ const apiProduct: ProductDef = {
       latest: true,
       sources: {},
       schema: 'static/swagger-27.json',
+      openapi3: 'static/openapi3-27.json',
     },
     ...['1.26', '1.25', '1.24', '1.23', '1.22'].map(
       (id): VersionDef => ({