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

update_api_docs.sh

@@ -1,11 +1,14 @@
 #!/bin/bash
 #
-# Regenerates the swagger definitions served by this site.
+# Regenerates the api definitions served by this site: the swagger 2.0 document
+# every gitea version ships, and the openapi 3.0 document gitea generates since
+# 1.27.
 #
 # Usage: ./update_api_docs.sh [--latest-only] [sed -i suffix] [extra sed args...]
 #
-#   --latest-only   only refresh static/swagger-latest.json from gitea main,
-#                   leaving the released static/swagger-<minor>.json untouched.
+#   --latest-only   only refresh static/swagger-latest.json and
+#                   static/openapi3-latest.json from gitea main, leaving the
+#                   released documents untouched.
 
 set -euo pipefail
 
@@ -42,6 +45,13 @@ SWAGGER_PATHS=(
   'templates/swagger/v1_json.tmpl'
 )
 
+# the openapi 3.0 document exists since gitea 1.27, with the same split between
+# a pre-generated json and a go template
+OPENAPI3_PATHS=(
+  'templates/swagger/v1-openapi3.generated.json'
+  'templates/swagger/v1_openapi3_json.tmpl'
+)
+
 # download_swagger <git ref> <output file>
 download_swagger() {
   local ref="$1" output="$2" path
@@ -55,6 +65,18 @@ download_swagger() {
   return 1
 }
 
+# download_openapi3 <git ref> <output file>, returns 1 for a version without one
+download_openapi3() {
+  local ref="$1" output="$2" path
+  for path in "${OPENAPI3_PATHS[@]}"; do
+    if curl --silent --fail --location --output "$output" \
+        "https://raw.githubusercontent.com/go-gitea/gitea/${ref}/${path}"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
 # rewrite_swagger <file> <version to display>
 rewrite_swagger() {
   local file="$1" version="$2"
@@ -69,17 +91,43 @@ rewrite_swagger() {
   inplace_sed "s#\"basePath\": \"{{AppSubUrl | JSEscape}}/api/v1\"#\"basePath\": \"https://gitea.com/api/v1\"#" "$file"
 }
 
-download_swagger 'refs/heads/main' v1_json.tmpl
-rewrite_swagger v1_json.tmpl 'dev'
-mv v1_json.tmpl static/swagger-latest.json
+# rewrite_openapi3 <file> <version to display>, the placeholders sit in `servers`
+# instead of `basePath`
+rewrite_openapi3() {
+  local file="$1" version="$2"
+  # gitea >= 1.28
+  inplace_sed "s|\"version\": \"0.0.0+GITEA-API-APP-VERSION\"|\"version\": \"${version}\"|" "$file"
+  inplace_sed 's|"url": "/GITEA-API-APP-SUBURL/api/v1"|"url": "https://gitea.com/api/v1"|' "$file"
+  # gitea 1.27
+  inplace_sed "s|\"version\": \"{{.SwaggerAppVer}}\"|\"version\": \"${version}\"|" "$file"
+  inplace_sed 's|"url": "{{.SwaggerAppSubUrl}}/api/v1"|"url": "https://gitea.com/api/v1"|' "$file"
+}
+
+# update_version <git ref> <version to display> <suffix of the static files>
+update_version() {
+  local ref="$1" version="$2" suffix="$3"
+
+  download_swagger "$ref" v1_json.tmpl
+  rewrite_swagger v1_json.tmpl "$version"
+  mv v1_json.tmpl "static/swagger-${suffix}.json"
+
+  if download_openapi3 "$ref" v1_openapi3_json.tmpl; then
+    rewrite_openapi3 v1_openapi3_json.tmpl "$version"
+    mv v1_openapi3_json.tmpl "static/openapi3-${suffix}.json"
+  else
+    # gitea < 1.27 only has the swagger 2.0 document
+    rm -f v1_openapi3_json.tmpl
+    echo "no openapi 3.0 document in ${ref}, keeping the swagger 2.0 one only" >&2
+  fi
+}
+
+update_version 'refs/heads/main' 'dev' 'latest'
 
 if [ "$LATEST_ONLY" -eq 1 ]; then
   exit 0
 fi
 
 for ver in '1.27.2' '1.26.4' '1.25.5' '1.24.7' '1.23.8' '1.22.6'; do
-  download_swagger "refs/tags/v${ver}" v1_json.tmpl
-  rewrite_swagger v1_json.tmpl "${ver}"
   minor=$(echo "$ver" | cut -d '.' -f 2)
-  mv v1_json.tmpl "static/swagger-$minor.json"
+  update_version "refs/tags/v${ver}" "${ver}" "${minor}"
 done