Skip to content

docs(extensions): don't use <details> blocks in <table> #2019

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
jamietanna merged 3 commits into from
Jul 15, 2025
Merged

docs(extensions): don't use <details> blocks in <table> #2019

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a918fc3
docs(extensions): don't use `<details>` blocks in `<table>`
Jul 15, 2025
f3bf795
docs(extensions): remove incorrectly duplicated note
Jul 15, 2025
1115bdf
docs(extensions): correct link to `x-omitempty` example
Jul 15, 2025
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
290 changes: 128 additions & 162 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2252,6 +2252,8 @@ type S struct {

As well as the core OpenAPI support, we also support the following OpenAPI extensions, as denoted by the [OpenAPI Specification Extensions](https://spec.openapis.org/oas/v3.0.3#specification-extensions).

The following extensions are supported:

<table>

<tr>
Expand All @@ -2261,9 +2263,6 @@ Extension
<th>
Description
</th>
<th>
Example usage
</th>
</tr>

<tr>
Expand All @@ -2276,8 +2275,122 @@ Example usage
<td>
Override the generated type definition (and optionally, add an import from another package)
</td>
</tr>

<tr>
<td>
<details>

`x-go-type-skip-optional-pointer`

</td>
<td>
Do not add a pointer type for optional fields in structs
</td>
</tr>

<tr>
<td>

`x-go-name`

</td>
<td>
Override the generated name of a field or a type
</td>
</tr>

<tr>
<td>

`x-go-type-name`

</td>
<td>
Override the generated name of a type
</td>
</tr>

<tr>
<td>

`x-omitempty`

</td>
<td>
Force the presence of the JSON tag `omitempty` on a field
</td>
</tr>

<tr>
<td>

`x-go-json-ignore`

</td>
<td>
When (un)marshaling JSON, ignore field(s)
</td>
</tr>

<tr>
<td>

`x-oapi-codegen-extra-tags`

</td>
<td>
Generate arbitrary struct tags to fields
</td>
</tr>

<tr>
<td>

`x-enum-varnames` / `x-enumNames`

</td>
<td>
Override generated variable names for enum constants
</td>
</tr>

<tr>
<td>

`x-deprecated-reason`

</td>
<td>
Add a GoDoc deprecation warning to a type
</td>
</tr>

<tr>
<td>

`x-order`

</td>
<td>
Explicitly order struct fields
</td>
</tr>

<tr>
<td>

`x-oapi-codegen-only-honour-go-name`

</td>
<td>
Only honour the `x-go-name` when generating field names
</td>
</tr>

</table>


### `x-go-type` / `x-go-type-import` - override the generated type definition (and optionally, add an import from another package)

Using the `x-go-type` (and optionally, `x-go-type-import` when you need to import another package) allows overriding the type that `oapi-codegen` determined the generated type should be.

Expand Down Expand Up @@ -2336,21 +2449,7 @@ type ClientWithExtension struct {

You can see this in more detail in [the example code](examples/extensions/xgotype/).

</details>
</td>
</tr>

<tr>
<td>

`x-go-type-skip-optional-pointer`

</td>
<td>
Do not add a pointer type for optional fields in structs
</td>
<td>
<details>
### `x-go-type-skip-optional-pointer` - do not add a pointer type for optional fields in structs

> [!TIP]
> If you prefer this behaviour, and prefer to not have to annotate your whole OpenAPI spec for this behaviour, you can use `output-options.prefer-skip-optional-pointer=true` to default this behaviour for all fields.
Expand Down Expand Up @@ -2405,21 +2504,7 @@ type ClientWithExtension struct {

You can see this in more detail in [the example code](examples/extensions/xgotypeskipoptionalpointer/).

</details>
</td>
</tr>

<tr>
<td>

`x-go-name`

</td>
<td>
Override the generated name of a field or a type
</td>
<td>
<details>
### `x-go-name` - override the generated name of a field or a type

By default, `oapi-codegen` will attempt to generate the name of fields and types in as best a way it can.

Expand Down Expand Up @@ -2476,21 +2561,7 @@ type ClientRenamedByExtension struct {

You can see this in more detail in [the example code](examples/extensions/xgoname/).

</details>
</td>
</tr>

<tr>
<td>

`x-go-type-name`

</td>
<td>
Override the generated name of a type
</td>
<td>
<details>
### `x-go-type-name` - Override the generated name of a type

> [!NOTE]
> Notice that this is subtly different to the `x-go-name`, which also applies to _fields_ within `struct`s.
Expand Down Expand Up @@ -2552,21 +2623,7 @@ type ClientRenamedByExtension struct {

You can see this in more detail in [the example code](examples/extensions/xgotypename/).

</details>
</td>
</tr>

<tr>
<td>

`x-omitempty`

</td>
<td>
Force the presence of the JSON tag `omitempty` on a field
</td>
<td>
<details>
### `x-omitempty` - force the presence of the JSON tag `omitempty` on a field

In a case that you may want to add the JSON struct tag `omitempty` to types that don't have one generated by default - for instance a required field - you can use the `x-omitempty` extension.

Expand Down Expand Up @@ -2619,23 +2676,9 @@ type ClientWithExtension struct {

Notice that the `ComplexField` is still generated in full, but the type will then be ignored with JSON marshalling.

You can see this in more detail in [the example code](examples/extensions/xgojsonignore/).
You can see this in more detail in [the example code](examples/extensions/xomitempty/).

</details>
</td>
</tr>

<tr>
<td>

`x-go-json-ignore`

</td>
<td>
When (un)marshaling JSON, ignore field(s)
</td>
<td>
<details>
### `x-go-json-ignore` - when (un)marshaling JSON, ignore field(s)

By default, `oapi-codegen` will generate `json:"..."` struct tags for all fields in a struct, so JSON (un)marshaling works.

Expand Down Expand Up @@ -2709,21 +2752,7 @@ Notice that the `ComplexField` is still generated in full, but the type will the

You can see this in more detail in [the example code](examples/extensions/xgojsonignore/).

</details>
</td>
</tr>

<tr>
<td>

`x-oapi-codegen-extra-tags`

</td>
<td>
Generate arbitrary struct tags to fields
</td>
<td>
<details>
### `x-oapi-codegen-extra-tags` - generate arbitrary struct tags to fields

If you're making use of a field's struct tags to i.e. apply validation, decide whether something should be logged, etc, you can use `x-oapi-codegen-extra-tags` to set additional tags for your generated types.

Expand Down Expand Up @@ -2780,21 +2809,7 @@ type ClientWithExtension struct {

You can see this in more detail in [the example code](examples/extensions/xoapicodegenextratags/).

</details>
</td>
</tr>

<tr>
<td>

`x-enum-varnames` / `x-enumNames`

</td>
<td>
Override generated variable names for enum constants
</td>
<td>
<details>
### `x-enum-varnames` / `x-enumNames` - override generated variable names for enum constants

When consuming an enum value from an external system, the name may not produce a nice variable name. Using the `x-enum-varnames` extension allows overriding the name of the generated variable names.

Expand Down Expand Up @@ -2863,21 +2878,7 @@ type ClientTypeWithVarNamesExtension string

You can see this in more detail in [the example code](examples/extensions/xenumnames/).

</details>
</td>
</tr>

<tr>
<td>

`x-deprecated-reason`

</td>
<td>
Add a GoDoc deprecation warning to a type
</td>
<td>
<details>
### `x-deprecated-reason` - add a GoDoc deprecation warning to a type

When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using `x-deprecated-reason`.

Expand Down Expand Up @@ -2935,28 +2936,12 @@ Notice that because we've not set `deprecated: true` to the `name` field, it doe

You can see this in more detail in [the example code](examples/extensions/xdeprecatedreason/).

</details>
</td>
</tr>

<tr>
<td>

`x-order`

</td>
<td>
Explicitly order struct fields
</td>
<td>
<details>
### `x-order` - explicitly order struct fields

Whether you like certain fields being ordered before others, or you want to perform more efficient packing of your structs, the `x-order` extension is here for you.

Note that `x-order` is 1-indexed - `x-order: 0` is not a valid value.

When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using `x-deprecated-reason`.

We can see this at play with the following schemas:

```yaml
Expand Down Expand Up @@ -3006,21 +2991,8 @@ type ClientWithExtension struct {

You can see this in more detail in [the example code](examples/extensions/xorder/).

</details>
</td>
</tr>

<tr>
<td>
### `x-oapi-codegen-only-honour-go-name` - only honour the `x-go-name` when generating field names

`x-oapi-codegen-only-honour-go-name`

</td>
<td>
Only honour the `x-go-name` when generating field names
</td>
<td>
<details>

> [!WARNING]
> Using this option may lead to cases where `oapi-codegen`'s rewriting of field names to prevent clashes with other types, or to prevent including characters that may not be valid Go field names.
Expand Down Expand Up @@ -3064,12 +3036,6 @@ type TypeWithUnexportedField struct {

You can see this in more detail in [the example code](examples/extensions/xoapicodegenonlyhonourgoname).

</details>
</td>
</tr>

</table>

## Request/response validation middleware

The generated code that `oapi-codegen` produces has some validation for some incoming data, such as checking for required headers, and when using the [strict server](#strict-server) you get some more validation around the correct usage of the response types.
Expand Down