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]>
127 lines
5.5 KiB
Markdown
127 lines
5.5 KiB
Markdown
# Gitea Docs 
|
|
|
|
The sources of [docs.gitea.com](https://docs.gitea.com), built with
|
|
[Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
|
|
|
|
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`, `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
|
|
reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
|
|
routes to that deployment.
|
|
|
|
## Development
|
|
|
|
```shell
|
|
make install # pnpm install
|
|
make serve-fast # english, the version served at the root, starts in seconds
|
|
make serve # the whole matrix, every version and language
|
|
make build # production build into sites/docs/dist
|
|
make check # type checks the site and its components
|
|
```
|
|
|
|
Search is built by Pagefind while the site is built, so it only answers on the
|
|
built site: use `make serve-built` to try it. With the Algolia credentials
|
|
(`PUBLIC_DOCSEARCH_APP_ID`, `PUBLIC_DOCSEARCH_API_KEY`) set, DocSearch is used
|
|
instead and works in `make serve` too.
|
|
|
|
`GITEA_DOCS_PRODUCTS`, `GITEA_DOCS_VERSIONS` and `GITEA_DOCS_LOCALES` (comma
|
|
separated) restrict what is built, which is what `make serve-fast` uses.
|
|
`GITEA_DOCS_STRICT_LINKS=true` turns the warnings about unresolved relative
|
|
markdown links into a build error.
|
|
|
|
`sites/docs/README.md` documents how the sources are mapped onto the site.
|
|
|
|
## Writing
|
|
|
|
Pages are plain markdown with the same frontmatter and admonitions as before:
|
|
frontmatter `slug`, `sidebar_position` and `sidebar_label` keep working, and so
|
|
do the `:::note` style admonitions and the `@version@` style release variables.
|
|
Relative `*.md` links are rewritten to urls while the site is built.
|
|
|
|
The order of the top level sidebar groups comes from `sidebars.js` (and
|
|
`versioned_sidebars/` for released versions), the label and order of every other
|
|
group from the `_category_.json` of its directory.
|
|
|
|
## Cutting a version
|
|
|
|
```shell
|
|
make cut-version PRODUCT=docs VERSION=1.28
|
|
make cut-version PRODUCT=runner VERSION=4
|
|
```
|
|
|
|
This freezes the current tree, its translations and its sidebar. The label of
|
|
the version, its release variables (`@version@`, `@dockerVersion@`, ...) and
|
|
which version is served at the root live in
|
|
`packages/content-loader/src/products.ts` and are edited by hand afterwards.
|
|
That file is the single source of truth for the product, version and language
|
|
matrix.
|
|
|
|
## API docs
|
|
|
|
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 the documents of gitea main
|
|
```
|
|
|
|
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.
|
|
|
|
## Runner docs
|
|
|
|
| Version | Content | URL |
|
|
| --- | --- | --- |
|
|
| develop | `runner-docs/` | `/runner/develop/` |
|
|
| current series | `runner-docs_versioned_docs/version-3/` | `/runner/` |
|
|
| older series | `runner-docs_versioned_docs/version-2/` | `/runner/2/` |
|
|
|
|
A version directory covers a whole release series (`version-3` documents every
|
|
`3.x` release), so a patch release only needs a content update, not a new
|
|
folder. Use floating image tags (`gitea/runner:3`) and links to the runner's
|
|
`main` branch in those pages to keep them valid across patch releases.
|
|
|
|
Its sidebar is written by hand: `runner-sidebars.js` for develop, and
|
|
`runner-docs_versioned_sidebars/version-<version>-sidebars.json` per documented
|
|
version.
|
|
|
|
The pages under `reference/` are generated from the runner sources — the command
|
|
line reference from `--help`, the example configuration from `generate-config`:
|
|
|
|
```shell
|
|
make update-runner-docs # develop docs, from the main branch of gitea/runner
|
|
make update-runner-docs-released # every series, from its newest stable tag
|
|
./update_runner_docs.sh v3.0.2 runner-docs_versioned_docs/version-3/reference
|
|
```
|
|
|
|
These are refreshed automatically as well: the `update runner reference`
|
|
workflow runs weekly and opens a pull request whenever the runner's CLI or
|
|
example configuration changed. Generating them needs Go, since the script builds
|
|
the runner binary.
|
|
|
|
## Deployment
|
|
|
|
`main` is built and published by the `Build and Publish Docs site` workflow, to
|
|
S3/CloudFront and to Cloudflare Pages. `cloudflare/_headers` sets the cache
|
|
policy and `cloudflare/_redirects` keeps the urls the site used to serve; both
|
|
are copied next to the build output by that workflow.
|
|
`cloudflare/docsearch-crawler.json` is the Algolia crawler configuration.
|
|
|
|
`/enterprise/` is served by another deployment and routed to it by a Cloudflare
|
|
worker that lives outside this repository.
|