Skip to content

feat(client): render x-stability-level in client Godoc #2598

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

Open
Anandb71 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(client): render x-stability-level in client Godoc #2598

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1356,6 +1356,7 @@ The following extensions are supported:
| `x-oapi-codegen-extra-tags` | Generate arbitrary struct tags to fields | [(docs)](docs/extensions.md#x-oapi-codegen-extra-tags) |
| `x-enum-varnames` / `x-enumNames` | Override generated variable names for enum constants | [(docs)](docs/extensions.md#x-enum-varnames--x-enumnames) |
| `x-deprecated-reason` | Add a GoDoc deprecation warning to a type | [(docs)](docs/extensions.md#x-deprecated-reason) |
| `x-stability-level` | Note an operation's stability level in the generated client GoDoc | [(docs)](docs/extensions.md#x-stability-level) |
| `x-order` | Explicitly order struct fields | [(docs)](docs/extensions.md#x-order) |
| `x-oapi-codegen-only-honour-go-name` | Only honour the `x-go-name` when generating field names | [(docs)](docs/extensions.md#x-oapi-codegen-only-honour-go-name) |
| `x-oapi-codegen-enum-merge` | Keep all the values of an `allOf`'s enums, with `schema-merging-behavior: v3` | [(docs)](docs/extensions.md#x-oapi-codegen-enum-merge) |
Expand Down
37 changes: 37 additions & 0 deletions docs/extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -621,6 +621,43 @@ 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-stability-level`

Note an operation's stability level in the generated client GoDoc.

When an operation sets `x-stability-level` to a string, that level is noted in the Godoc of the generated client methods (`ClientInterface`, `Client`, `ClientWithResponsesInterface` and `ClientWithResponses`), so callers can see whether the API is potentially unstable. The value is rendered as-is; [oasdiff](https://github.com/oasdiff/oasdiff/blob/main/docs/STABILITY.md) defines the levels `draft`, `alpha`, `beta` and `stable`, and treats operations without the extension as `stable`. Operations without the extension get no extra Godoc.

We can see this at play with the following operation:

```yaml
openapi: "3.0.0"
info:
version: 1.0.0
title: x-stability-level
paths:
/pets:
get:
operationId: listPets
summary: List pets
x-stability-level: alpha
responses:
"200":
description: A list of pets
```

From here, the generated client method is documented as:

```go
// ListPets List pets
//
// Corresponds with GET /pets (the `ListPets` operationId).
//
// This operation has been marked with the `alpha` stability level upstream (via `x-stability-level`).
ListPets(ctx context.Context, reqEditors ...RequestEditorFn) (*http.Response, error)
```

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

## `x-order`

Explicitly order struct fields.
Expand Down
62 changes: 62 additions & 0 deletions examples/extensions/xstabilitylevel/api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
openapi: "3.0.0"
info:
version: 1.0.0
title: x-stability-level
paths:
/pets:
get:
operationId: listPets
summary: List pets
x-stability-level: alpha
responses:
"200":
description: A list of pets
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Pet"
post:
operationId: createPet
summary: Create a pet
x-stability-level: beta
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
responses:
"201":
description: The created pet
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
/pets/{id}:
get:
operationId: getPet
summary: Get a pet
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: A pet
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
components:
schemas:
Pet:
type: object
required:
- name
properties:
name:
type: string
6 changes: 6 additions & 0 deletions examples/extensions/xstabilitylevel/cfg.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# yaml-language-server: $schema=../../../configuration-schema.json
package: xstabilitylevel
output: gen.go
generate:
models: true
client: true
Loading
Loading