Skip to content

docs: add documentation for @description tag in enum variants #1108

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
starfy84 wants to merge 1 commit into
base: DX-25435-enums-deprecated
Choose a base branch
from
Open

docs: add documentation for @description tag in enum variants #1108

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
35 changes: 29 additions & 6 deletions packages/openapi-generator/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -498,11 +498,16 @@ const Schema = t.type({
});
```

#### 6.2.4 Deprecated Enum Values
#### 6.2.4 Enum Documentation

When using `t.keyof` to define enums, you can mark specific enum values as deprecated
using the `@deprecated` tag. Deprecated values will be collected into an
`x-enumsDeprecated` array in the OpenAPI specification.
When using `t.keyof` to define enums, you can add descriptions and deprecation notices
to individual enum values. These will be output as `x-enumDescriptions` and
`x-enumsDeprecated` in the OpenAPI specification.

- **`@description`** - Adds a description for a specific enum value. All enum value
descriptions are collected into an `x-enumDescriptions` object in the OpenAPI spec.
- **`@deprecated`** - Marks specific enum values as deprecated. All deprecated enum
values are collected into an `x-enumsDeprecated` array in the OpenAPI spec.

```typescript
import * as t from 'io-ts';
Expand All @@ -512,11 +517,23 @@ import * as t from 'io-ts';
*/
export const TransactionStatus = t.keyof(
{
/**
* @description Transaction is waiting for approval from authorized users
*/
pendingApproval: 1,
/** @deprecated */
/**
* @description Transaction was canceled by the user
* @deprecated
*/
canceled: 1,
/** @deprecated */
/**
* @description Transaction was rejected by approvers
* @deprecated
*/
rejected: 1,
/**
* @description Transaction has been successfully completed
*/
completed: 1,
},
'TransactionStatus',
Expand All @@ -530,6 +547,12 @@ This will generate the following OpenAPI schema:
"TransactionStatus": {
"type": "string",
"enum": ["pendingApproval", "canceled", "rejected", "completed"],
"x-enumDescriptions": {
"pendingApproval": "Transaction is waiting for approval from authorized users",
"canceled": "Transaction was canceled by the user",
"rejected": "Transaction was rejected by approvers",
"completed": "Transaction has been successfully completed"
},
"x-enumsDeprecated": ["canceled", "rejected"]
}
}
Expand Down