The scheduled `update swagger files` job has failed on **every** run since it was added (I checked the run list on gitea.com, ~250 consecutive failures). Two reasons:
1. Upstream moved the file: `go-gitea/gitea` main no longer has `templates/swagger/v1_json.tmpl`, it is now `templates/swagger/v1-swagger.generated.json`, and the placeholders changed from `{{.SwaggerAppVer}}` / `{{.SwaggerAppSubUrl}}` to `0.0.0+GITEA-API-APP-VERSION` / `/GITEA-API-APP-SUBURL/api/v1`. Because the script used `curl --silent` without `--fail`, the 404 body was written into `static/swagger-latest.json`.
2. `main` is protected (`required_approvals=1`), so the job's `git push` to main could never succeed.
Changes:
- `update_api_docs.sh`: `set -euo pipefail`, download with `--fail` (a broken download now aborts instead of committing garbage), try the new generated json first and fall back to the old template for released tags, handle the 1.28+/1.24+/<1.24 placeholder variants, and add a `--latest-only` flag.
- `Makefile`: new `update-api-docs-latest` target for the cron job; `clean` no longer deletes the committed `static/swagger-*.json` files (deleting them breaks `make build`).
- `.gitea/workflows/update_swagger.yaml`: every 12h (plus `workflow_dispatch`) it regenerates only `static/swagger-latest.json`, verifies no placeholder is left and the file is valid JSON, force pushes to `bot/update-swagger-latest` and opens a pull request via the API (HTTP 409 = a PR is already open, it just now points at the new commit). It skips entirely when the bot branch already carries the same file, so no PR churn.
- `README.md`: document the two make targets and the automation.
`secrets.DEPLOY_TOKEN` must belong to a real user with `write:repository` so the PR checks are triggered; the job fails with a clear message if it is empty.
Tested locally in a scratch clone: `make update-api-docs-latest` produces a valid `dev` spec with no placeholders left, `make update-api-docs` still regenerates all released versions, and the workflow shell logic was simulated against a local bare repo for all three paths (open PR / bot branch already up to date / main already up to date), including a shallow clone to confirm `fetch-depth: 1` force pushes work.
Fixes#454
Reviewed-on: https://gitea.com/gitea/docs/pulls/481
Reviewed-by: techknowlogick <[email protected]>
# Changes
- Added [redocusaurus](https://github.com/rohit-gohri/redocusaurus) package to display swagger api with reference to [woodpecker](https://github.com/woodpecker-ci/woodpecker/tree/master/docs)
- Change `sed` for swagger.json for proper version and baseurl.
- Add a dropdown for different api versions. (screenshot below)
- On API pages, only API version dropdown will show(hide locale dropdown, version dropdown for doc, and doc search)
- Allow build CSR API pages for development so it saves building time.
# Screenshots
Search:
Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/32
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
# Main changes and Some notices
- Chines Docs should be put into corresponding versions' folders under `i18n/zh-cn/docusaurus-plugin-content-docs`. See [translate-markdown-files](https://docusaurus.io/docs/i18n/tutorial#translate-markdown-files) for reference. And also [srs-docs](https://github.com/ossrs/srs-docs) is a project that can be used as a reference. So changed the related paths in `loop_docs*` scripts.
- The markdown files under `docs/<version>` and `i18n/zh-cn/docusaurus-plugin-content-docs/<version>` must have the same name to be referred as translated. Files inside docs are corresponding to `current` version.
For example, `docs/administration/mail-templates.md` and `i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/mail-templates.md`. Filename of `mail-templates.md` must be the same (cannot be `mail-templates.zh-cn.md` and `mail-templates.us-en.md`)
So trim the `.en-us.md` and `.zh-cn.md` to `.md` to ensure the same names inside `loop_docs*` scripts.
- Used `npx docusaurus write-translations --locale zh-cn` to do sidebar, footer, and header translations, so no need to keep `sideBarCN` anymore. [reference](https://docusaurus.io/docs/cli#docusaurus-write-translations-sitedir)
- Local Tests for `en` and `zh-cn` are separeted, run the following on local respectly to test them
```bash
# test en version
npm run start
# test zh-cn version
npm run start -- --locale zh-cn
```
- If wants to test `en` and `zh-cn` both at the same time, run build and serve
```
npm run build
npm run serve
```
- Added some indexed page, for example:
Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/13
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
Lunny Xiao