mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-17 19:55:34 +00:00
Lunny Xiaoandbircni
3258717d62
Two unrelated but small fixes, closes #258 and closes #32. **The reference does not name its types (#258)** Since the api reference is rendered from the openapi 3.0 document, a field of type `ReviewStateType` is rendered as the bare string enum the `$ref` points at: starlight-openapi dereferences everything and the schema has no `title`, so the name of the type is nowhere on the page. Searching the current reference for `ReviewStateType` returns nothing, which is what the issue reports (the plugin also has no route for `components/schemas`, so there is no page per type either). `normalizeSchema()` now titles every named schema of an openapi 3.0 document with its own name, which the plugin renders next to the type of a field: - before: `state` · `string` · Allowed values: APPROVED … - after: `state` · `ReviewStateType` · `string` · Allowed values: APPROVED … The go doc comments start with the name of the type, so the description would repeat it ("ChangeFilesOptions — ChangeFilesOptions options for creating …"); a leading `<name> ` is stripped from the description. For the record, how the three generations of documents describe that type: | Versions | Type name | Allowed values | | --- | --- | --- | | 1.22 – 1.25 (swagger, `ReviewStateType` definition without `enum`) | shown | missing | | 1.26 – 1.27 (swagger, enum inlined upstream) | missing | shown | | 1.27, next (openapi 3.0, with this change) | shown | shown | The released swagger documents are frozen, so 1.22 – 1.26 keep what they have; from 1.27 on the reference answers the question the issue asks. **Gmail needs an app password (#32)** The configuration in the guide is still correct after Google turned off password-only access, because it already asks for an app password. What was missing is why there is no alternative: Gitea's mailer authenticates with `CRAM-MD5`, `PLAIN` or `LOGIN` and has no XOAUTH2, so "Sign in with Google" is not an option. Added that, together with the two things people run into — an app password needs 2-step verification and a Workspace administrator can disable app passwords for the domain — and the `587` + `smtp+starttls` variant. Verified by building the api and the next docs: the type names show up on the operation pages, the descriptions are not duplicated, and 1.26 and older are unchanged. `pnpm check` passes. <!-- cloudflare-preview --> Preview: https://pr-541.docs-gitea-com.pages.dev --------- Co-authored-by: bircni <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/541 Reviewed-by: bircni <[email protected]> Co-authored-by: Lunny Xiao <[email protected]>