Skip to content

Doc Maintainers #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fredbi merged 5 commits into from
Jun 27, 2026
Merged

Doc Maintainers #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2072c8e
docs(doc-site): one page per swagger:* annotation; alpha-sort the index
fredbi Jun 27, 2026
1bf0666
docs(doc-site): rework annotation pages — Usage quick-form + live exa…
fredbi Jun 27, 2026
032a639
docs(doc-site): restructure keyword reference into class pages
fredbi Jun 27, 2026
32c9ee1
docs(doc-site): railroad (syntax) diagrams for the EBNF grammar
fredbi Jun 27, 2026
05d042b
docs(doc-site): document swagger:title / swagger:description annotations
fredbi Jun 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions .github/workflows/update-doc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,18 +53,26 @@ jobs:
git fetch upstream --prune --update-shallow --tags 'refs/tags/*:refs/tags/*'
git fetch origin --prune --update-shallow --tags 'refs/tags/*:refs/tags/*'
-
name: Initialize theme
name: Initialize theme and assets
env:
RELEARN_VERSION: 9.0.3
MERMAID_VERSION: 11.16.0
run: |
cd hack/doc-site/hugo

# Clone theme
# Clone theme (not committed)
curl -sL -o relearn.tgz https://github.com/McShelby/hugo-theme-relearn/archive/refs/tags/"${RELEARN_VERSION}".tar.gz
tar xf relearn.tgz
rm -rf themes/hugo-relearn
mv "hugo-theme-relearn-${RELEARN_VERSION}" hugo-relearn
mv hugo-relearn themes/

# Fetch vendored Mermaid (not committed) — the railroad shortcode needs
# >= 11.16, newer than the theme's bundled Mermaid; served as a local
# static asset so the rendered site makes no runtime CDN calls.
mkdir -p themes/codescan-static/js/mermaid11
curl -sL -o themes/codescan-static/js/mermaid11/mermaid.min.js \
https://cdn.jsdelivr.net/npm/mermaid@"${MERMAID_VERSION}"/dist/mermaid.min.js
-
name: Prepare config
run: |
Expand Down
36 changes: 19 additions & 17 deletions docs/doc-site/annotation-index/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,23 +12,25 @@ tutorial that shows the annotation as runnable Go next to the spec it produces;

| Annotation | Attaches to | Produces | By example | Reference |
|---|---|---|---|---|
| `swagger:meta` | package doc | top-level `info`, `host`, `basePath`, `schemes`, … | [example]({{% relref "/tutorials/document-metadata#swaggermeta" %}}) | [reference]({{% relref "/maintainers/annotations#swaggermeta" %}}) |
| `swagger:model` | type declaration | a `definitions` entry | [example]({{% relref "/tutorials/model-definitions#swaggermodel" %}}) | [reference]({{% relref "/maintainers/annotations#swaggermodel" %}}) |
| `swagger:strfmt` | type declaration | `{type: string, format: …}` at every use | [example]({{% relref "/tutorials/model-definitions#swaggerstrfmt" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerstrfmt" %}}) |
| `swagger:enum` | named type | an `enum` array (+ `x-go-enum-desc`) | [example]({{% relref "/tutorials/model-definitions#swaggerenum" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerenum" %}}) |
| `swagger:allOf` | embedded field / struct | an `allOf` composition | [example]({{% relref "/tutorials/model-definitions#swaggerallof" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerallof" %}}) |
| `swagger:alias` *(deprecated)* | type alias | **no effect** — alias rendering is controlled by Go aliases + options | [how-to]({{% relref "alias-rendering" %}}) | [reference]({{% relref "/maintainers/annotations#swaggeralias--deprecated" %}}) |
| `swagger:route` | func / var doc | a `paths` entry + operation | [example]({{% relref "/tutorials/routes-and-operations#swaggerroute" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerroute" %}}) |
| `swagger:operation` | func / var doc | a `paths` entry (YAML body) | [example]({{% relref "/tutorials/routes-and-operations#swaggeroperation" %}}) | [reference]({{% relref "/maintainers/annotations#swaggeroperation" %}}) |
| `swagger:parameters` | struct declaration | parameters on the named operation(s) | [example]({{% relref "/tutorials/routes-and-operations#swaggerparameters" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerparameters" %}}) |
| `swagger:response` | struct declaration | a `responses` entry | [example]({{% relref "/tutorials/routes-and-operations#swaggerresponse" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerresponse" %}}) |
| `swagger:ignore` | type / field doc | excludes the declaration | [example]({{% relref "/tutorials/model-definitions#swaggerignore" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerignore" %}}) |
| `swagger:name` | field / method doc | renames a JSON property | [example]({{% relref "/tutorials/model-definitions#swaggername" %}}) | [reference]({{% relref "/maintainers/annotations#swaggername" %}}) |
| `swagger:type` | type / field doc | overrides the inferred Swagger type | [example]({{% relref "/tutorials/model-definitions#swaggertype" %}}) | [reference]({{% relref "/maintainers/annotations#swaggertype" %}}) |
| `swagger:additionalProperties` | type doc | object `additionalProperties` (open / closed / typed) | [example]({{% relref "/tutorials/maps-and-free-form-objects#open--closed-objects" %}}) | [reference]({{% relref "/maintainers/annotations#swaggeradditionalproperties" %}}) |
| `swagger:patternProperties` | type doc | typed `patternProperties` (regex → value) | [example]({{% relref "/tutorials/maps-and-free-form-objects#pattern-properties" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerpatternproperties" %}}) |
| `swagger:file` | param / response field | `{type: file}` | [example]({{% relref "/tutorials/routes-and-operations#swaggerfile" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerfile" %}}) |
| `swagger:default` | value / field doc | a default-value anchor | [example]({{% relref "/tutorials/examples-and-defaults#swaggerdefault" %}}) | [reference]({{% relref "/maintainers/annotations#swaggerdefault" %}}) |
| `swagger:additionalProperties` | type doc | object `additionalProperties` (open / closed / typed) | [example]({{% relref "/tutorials/maps-and-free-form-objects#open--closed-objects" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-additionalproperties" %}}) |
| `swagger:alias` *(deprecated)* | type alias | **no effect** — alias rendering is controlled by Go aliases + options | [how-to]({{% relref "alias-rendering" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-alias" %}}) |
| `swagger:allOf` | embedded field / struct | an `allOf` composition | [example]({{% relref "/tutorials/model-definitions#swaggerallof" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-allof" %}}) |
| `swagger:default` | value / field doc | a default-value anchor | [example]({{% relref "/tutorials/examples-and-defaults#swaggerdefault" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-default" %}}) |
| `swagger:description` | type / field / response doc | overrides the `description` (verbatim body with `\|`) | [how-to]({{% relref "overriding-titles-and-descriptions" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-description" %}}) |
| `swagger:enum` | named type | an `enum` array (+ `x-go-enum-desc`) | [example]({{% relref "/tutorials/model-definitions#swaggerenum" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-enum" %}}) |
| `swagger:file` | param / response field | `{type: file}` | [example]({{% relref "/tutorials/routes-and-operations#swaggerfile" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-file" %}}) |
| `swagger:ignore` | type / field doc | excludes the declaration | [example]({{% relref "/tutorials/model-definitions#swaggerignore" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-ignore" %}}) |
| `swagger:meta` | package doc | top-level `info`, `host`, `basePath`, `schemes`, … | [example]({{% relref "/tutorials/document-metadata#swaggermeta" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-meta" %}}) |
| `swagger:model` | type declaration | a `definitions` entry | [example]({{% relref "/tutorials/model-definitions#swaggermodel" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-model" %}}) |
| `swagger:name` | field / method doc | renames a JSON property | [example]({{% relref "/tutorials/model-definitions#swaggername" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-name" %}}) |
| `swagger:operation` | func / var doc | a `paths` entry (YAML body) | [example]({{% relref "/tutorials/routes-and-operations#swaggeroperation" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-operation" %}}) |
| `swagger:parameters` | struct declaration | parameters on the named operation(s) | [example]({{% relref "/tutorials/routes-and-operations#swaggerparameters" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-parameters" %}}) |
| `swagger:patternProperties` | type doc | typed `patternProperties` (regex → value) | [example]({{% relref "/tutorials/maps-and-free-form-objects#pattern-properties" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-patternproperties" %}}) |
| `swagger:response` | struct declaration | a `responses` entry | [example]({{% relref "/tutorials/routes-and-operations#swaggerresponse" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-response" %}}) |
| `swagger:route` | func / var doc | a `paths` entry + operation | [example]({{% relref "/tutorials/routes-and-operations#swaggerroute" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-route" %}}) |
| `swagger:strfmt` | type declaration | `{type: string, format: …}` at every use | [example]({{% relref "/tutorials/model-definitions#swaggerstrfmt" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-strfmt" %}}) |
| `swagger:title` | type / field doc | overrides the `title` | [how-to]({{% relref "overriding-titles-and-descriptions" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-title" %}}) |
| `swagger:type` | type / field doc | overrides the inferred Swagger type | [example]({{% relref "/tutorials/model-definitions#swaggertype" %}}) | [reference]({{% relref "/maintainers/annotations/swagger-type" %}}) |

## Keywords, not annotations

Expand Down
Loading
Loading