Skip to content

Commit 95920ff

Browse files
Jamie Tannajamietanna
Jamie Tanna
authored and
jamietanna
committed
docs(extensions): don't use <details> blocks in <table>
This is significantly hard to author, and makes it harder to read as rendered Markdown, too, so let's expand these out. We can retain the table view as a quick reference.
1 parent a5da684 commit 95920ff

1 file changed

Lines changed: 127 additions & 159 deletions

File tree

‎README.md‎

Lines changed: 127 additions & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -2252,6 +2252,8 @@ type S struct {
22522252

22532253
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).
22542254

2255+
The following extensions are supported:
2256+
22552257
<table>
22562258

22572259
<tr>
@@ -2261,9 +2263,6 @@ Extension
22612263
<th>
22622264
Description
22632265
</th>
2264-
<th>
2265-
Example usage
2266-
</th>
22672266
</tr>
22682267

22692268
<tr>
@@ -2276,8 +2275,122 @@ Example usage
22762275
<td>
22772276
Override the generated type definition (and optionally, add an import from another package)
22782277
</td>
2278+
</tr>
2279+
2280+
<tr>
22792281
<td>
2280-
<details>
2282+
2283+
`x-go-type-skip-optional-pointer`
2284+
2285+
</td>
2286+
<td>
2287+
Do not add a pointer type for optional fields in structs
2288+
</td>
2289+
</tr>
2290+
2291+
<tr>
2292+
<td>
2293+
2294+
`x-go-name`
2295+
2296+
</td>
2297+
<td>
2298+
Override the generated name of a field or a type
2299+
</td>
2300+
</tr>
2301+
2302+
<tr>
2303+
<td>
2304+
2305+
`x-go-type-name`
2306+
2307+
</td>
2308+
<td>
2309+
Override the generated name of a type
2310+
</td>
2311+
</tr>
2312+
2313+
<tr>
2314+
<td>
2315+
2316+
`x-omitempty`
2317+
2318+
</td>
2319+
<td>
2320+
Force the presence of the JSON tag `omitempty` on a field
2321+
</td>
2322+
</tr>
2323+
2324+
<tr>
2325+
<td>
2326+
2327+
`x-go-json-ignore`
2328+
2329+
</td>
2330+
<td>
2331+
When (un)marshaling JSON, ignore field(s)
2332+
</td>
2333+
</tr>
2334+
2335+
<tr>
2336+
<td>
2337+
2338+
`x-oapi-codegen-extra-tags`
2339+
2340+
</td>
2341+
<td>
2342+
Generate arbitrary struct tags to fields
2343+
</td>
2344+
</tr>
2345+
2346+
<tr>
2347+
<td>
2348+
2349+
`x-enum-varnames` / `x-enumNames`
2350+
2351+
</td>
2352+
<td>
2353+
Override generated variable names for enum constants
2354+
</td>
2355+
</tr>
2356+
2357+
<tr>
2358+
<td>
2359+
2360+
`x-deprecated-reason`
2361+
2362+
</td>
2363+
<td>
2364+
Add a GoDoc deprecation warning to a type
2365+
</td>
2366+
</tr>
2367+
2368+
<tr>
2369+
<td>
2370+
2371+
`x-order`
2372+
2373+
</td>
2374+
<td>
2375+
Explicitly order struct fields
2376+
</td>
2377+
</tr>
2378+
2379+
<tr>
2380+
<td>
2381+
2382+
`x-oapi-codegen-only-honour-go-name`
2383+
2384+
</td>
2385+
<td>
2386+
Only honour the `x-go-name` when generating field names
2387+
</td>
2388+
</tr>
2389+
2390+
</table>
2391+
2392+
2393+
### `x-go-type` / `x-go-type-import` - override the generated type definition (and optionally, add an import from another package)
22812394

22822395
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.
22832396

@@ -2336,21 +2449,7 @@ type ClientWithExtension struct {
23362449

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

2339-
</details>
2340-
</td>
2341-
</tr>
2342-
2343-
<tr>
2344-
<td>
2345-
2346-
`x-go-type-skip-optional-pointer`
2347-
2348-
</td>
2349-
<td>
2350-
Do not add a pointer type for optional fields in structs
2351-
</td>
2352-
<td>
2353-
<details>
2452+
### `x-go-type-skip-optional-pointer` - do not add a pointer type for optional fields in structs
23542453

23552454
> [!TIP]
23562455
> 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 {
24052504

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

2408-
</details>
2409-
</td>
2410-
</tr>
2411-
2412-
<tr>
2413-
<td>
2414-
2415-
`x-go-name`
2416-
2417-
</td>
2418-
<td>
2419-
Override the generated name of a field or a type
2420-
</td>
2421-
<td>
2422-
<details>
2507+
### `x-go-name` - override the generated name of a field or a type
24232508

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

@@ -2476,21 +2561,7 @@ type ClientRenamedByExtension struct {
24762561

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

2479-
</details>
2480-
</td>
2481-
</tr>
2482-
2483-
<tr>
2484-
<td>
2485-
2486-
`x-go-type-name`
2487-
2488-
</td>
2489-
<td>
2490-
Override the generated name of a type
2491-
</td>
2492-
<td>
2493-
<details>
2564+
### `x-go-type-name` - Override the generated name of a type
24942565

24952566
> [!NOTE]
24962567
> 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 {
25522623

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

2555-
</details>
2556-
</td>
2557-
</tr>
2558-
2559-
<tr>
2560-
<td>
2561-
2562-
`x-omitempty`
2563-
2564-
</td>
2565-
<td>
2566-
Force the presence of the JSON tag `omitempty` on a field
2567-
</td>
2568-
<td>
2569-
<details>
2626+
### `x-omitempty` - force the presence of the JSON tag `omitempty` on a field
25702627

25712628
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.
25722629

@@ -2621,21 +2678,7 @@ Notice that the `ComplexField` is still generated in full, but the type will the
26212678

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

2624-
</details>
2625-
</td>
2626-
</tr>
2627-
2628-
<tr>
2629-
<td>
2630-
2631-
`x-go-json-ignore`
2632-
2633-
</td>
2634-
<td>
2635-
When (un)marshaling JSON, ignore field(s)
2636-
</td>
2637-
<td>
2638-
<details>
2681+
### `x-go-json-ignore` - when (un)marshaling JSON, ignore field(s)
26392682

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

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

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

2712-
</details>
2713-
</td>
2714-
</tr>
2715-
2716-
<tr>
2717-
<td>
2718-
2719-
`x-oapi-codegen-extra-tags`
2720-
2721-
</td>
2722-
<td>
2723-
Generate arbitrary struct tags to fields
2724-
</td>
2725-
<td>
2726-
<details>
2755+
### `x-oapi-codegen-extra-tags` - generate arbitrary struct tags to fields
27272756

27282757
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.
27292758

@@ -2780,21 +2809,7 @@ type ClientWithExtension struct {
27802809

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

2783-
</details>
2784-
</td>
2785-
</tr>
2786-
2787-
<tr>
2788-
<td>
2789-
2790-
`x-enum-varnames` / `x-enumNames`
2791-
2792-
</td>
2793-
<td>
2794-
Override generated variable names for enum constants
2795-
</td>
2796-
<td>
2797-
<details>
2812+
### `x-enum-varnames` / `x-enumNames` - override generated variable names for enum constants
27982813

27992814
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.
28002815

@@ -2863,21 +2878,7 @@ type ClientTypeWithVarNamesExtension string
28632878

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

2866-
</details>
2867-
</td>
2868-
</tr>
2869-
2870-
<tr>
2871-
<td>
2872-
2873-
`x-deprecated-reason`
2874-
2875-
</td>
2876-
<td>
2877-
Add a GoDoc deprecation warning to a type
2878-
</td>
2879-
<td>
2880-
<details>
2881+
### `x-deprecated-reason` - add a GoDoc deprecation warning to a type
28812882

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

@@ -2935,21 +2936,7 @@ Notice that because we've not set `deprecated: true` to the `name` field, it doe
29352936

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

2938-
</details>
2939-
</td>
2940-
</tr>
2941-
2942-
<tr>
2943-
<td>
2944-
2945-
`x-order`
2946-
2947-
</td>
2948-
<td>
2949-
Explicitly order struct fields
2950-
</td>
2951-
<td>
2952-
<details>
2939+
### `x-order` - explicitly order struct fields
29532940

29542941
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.
29552942

@@ -3006,21 +2993,8 @@ type ClientWithExtension struct {
30062993

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

3009-
</details>
3010-
</td>
3011-
</tr>
3012-
3013-
<tr>
3014-
<td>
2996+
### `x-oapi-codegen-only-honour-go-name` - only honour the `x-go-name` when generating field names
30152997

3016-
`x-oapi-codegen-only-honour-go-name`
3017-
3018-
</td>
3019-
<td>
3020-
Only honour the `x-go-name` when generating field names
3021-
</td>
3022-
<td>
3023-
<details>
30242998

30252999
> [!WARNING]
30263000
> 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 +3038,6 @@ type TypeWithUnexportedField struct {
30643038

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

3067-
</details>
3068-
</td>
3069-
</tr>
3070-
3071-
</table>
3072-
30733041
## Request/response validation middleware
30743042

30753043
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.

0 commit comments

Comments
 (0)