diff --git a/README.md b/README.md
index a0783c0c13..ce9f665a5d 100644
--- a/README.md
+++ b/README.md
@@ -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:
+
@@ -2261,9 +2263,6 @@ Extension
|
Description
|
-
-Example usage
- |
@@ -2276,8 +2275,122 @@ Example usage
|
Override the generated type definition (and optionally, add an import from another package)
|
+
+
+
-
+
+`x-go-type-skip-optional-pointer`
+
+ |
+
+Do not add a pointer type for optional fields in structs
+ |
+
+
+
+|
+
+`x-go-name`
+
+ |
+
+Override the generated name of a field or a type
+ |
+
+
+
+|
+
+`x-go-type-name`
+
+ |
+
+Override the generated name of a type
+ |
+
+
+
+|
+
+`x-omitempty`
+
+ |
+
+Force the presence of the JSON tag `omitempty` on a field
+ |
+
+
+
+|
+
+`x-go-json-ignore`
+
+ |
+
+When (un)marshaling JSON, ignore field(s)
+ |
+
+
+
+|
+
+`x-oapi-codegen-extra-tags`
+
+ |
+
+Generate arbitrary struct tags to fields
+ |
+
+
+
+|
+
+`x-enum-varnames` / `x-enumNames`
+
+ |
+
+Override generated variable names for enum constants
+ |
+
+
+
+|
+
+`x-deprecated-reason`
+
+ |
+
+Add a GoDoc deprecation warning to a type
+ |
+
+
+
+|
+
+`x-order`
+
+ |
+
+Explicitly order struct fields
+ |
+
+
+
+|
+
+`x-oapi-codegen-only-honour-go-name`
+
+ |
+
+Only honour the `x-go-name` when generating field names
+ |
+
+
+
+
+
+### `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.
@@ -2336,21 +2449,7 @@ type ClientWithExtension struct {
You can see this in more detail in [the example code](examples/extensions/xgotype/).
-
-
-
-
-
-|
-
-`x-go-type-skip-optional-pointer`
-
- |
-
-Do not add a pointer type for optional fields in structs
- |
-
-
+### `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.
@@ -2405,21 +2504,7 @@ type ClientWithExtension struct {
You can see this in more detail in [the example code](examples/extensions/xgotypeskipoptionalpointer/).
-
- |
-
-
-
-|
-
-`x-go-name`
-
- |
-
-Override the generated name of a field or a type
- |
-
-
+### `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.
@@ -2476,21 +2561,7 @@ type ClientRenamedByExtension struct {
You can see this in more detail in [the example code](examples/extensions/xgoname/).
-
- |
-
-
-
-|
-
-`x-go-type-name`
-
- |
-
-Override the generated name of a type
- |
-
-
+### `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.
@@ -2552,21 +2623,7 @@ type ClientRenamedByExtension struct {
You can see this in more detail in [the example code](examples/extensions/xgotypename/).
-
- |
-
-
-
-|
-
-`x-omitempty`
-
- |
-
-Force the presence of the JSON tag `omitempty` on a field
- |
-
-
+### `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.
@@ -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/).
-
- |
-
-
-
-|
-
-`x-go-json-ignore`
-
- |
-
-When (un)marshaling JSON, ignore field(s)
- |
-
-
+### `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.
@@ -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/).
-
- |
-
-
-
-|
-
-`x-oapi-codegen-extra-tags`
-
- |
-
-Generate arbitrary struct tags to fields
- |
-
-
+### `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.
@@ -2780,21 +2809,7 @@ type ClientWithExtension struct {
You can see this in more detail in [the example code](examples/extensions/xoapicodegenextratags/).
-
- |
-
-
-
-|
-
-`x-enum-varnames` / `x-enumNames`
-
- |
-
-Override generated variable names for enum constants
- |
-
-
+### `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.
@@ -2863,21 +2878,7 @@ type ClientTypeWithVarNamesExtension string
You can see this in more detail in [the example code](examples/extensions/xenumnames/).
-
- |
-
-
-
-|
-
-`x-deprecated-reason`
-
- |
-
-Add a GoDoc deprecation warning to a type
- |
-
-
+### `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`.
@@ -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/).
-
- |
-
-
-
-|
-
-`x-order`
-
- |
-
-Explicitly order struct fields
- |
-
-
+### `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
@@ -3006,21 +2991,8 @@ type ClientWithExtension struct {
You can see this in more detail in [the example code](examples/extensions/xorder/).
-
- |
-
-
-
-|
+### `x-oapi-codegen-only-honour-go-name` - only honour the `x-go-name` when generating field names
-`x-oapi-codegen-only-honour-go-name`
-
- |
-
-Only honour the `x-go-name` when generating field names
- |
-
-
> [!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.
@@ -3064,12 +3036,6 @@ type TypeWithUnexportedField struct {
You can see this in more detail in [the example code](examples/extensions/xoapicodegenonlyhonourgoname).
-
- |
-
-
-
-
## 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.