Skip to content

Commit 128c2be

Browse files
radist2sradist2s
authored
Merge pull request #408 from OpenAPI-Qraft/chore/asyncapi-descriptions-tsdoc
feat(asyncapi-typescript-plugin): generate descriptions as TSDoc instead of type properties
2 parents 8a50471 + 9eb4506 commit 128c2be

11 files changed

Lines changed: 133 additions & 148 deletions

‎.changeset/yummy-rooms-type.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@qraft/asyncapi-typescript-plugin': patch
3+
---
4+
5+
Generate AsyncAPI descriptions as TSDoc comments consistently instead of `description` type properties in generated output. Updated snapshots accordingly.

‎packages/asyncapi-typescript-plugin/src/__snapshots__/no-extra-options.ts.snapshot.ts‎

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@
55

66
export interface servers {
77
"events-test": components["servers"]["events-test"];
8+
/** @description Production WebSocket server for events (lighting measurements) secured with TLS */
89
"events-prod": {
910
host: "prod-events.example.com";
1011
protocol: "wss";
11-
description: "Production WebSocket server for events (lighting measurements) secured with TLS";
1212
};
13+
/** @description Test WebSocket server for commands (turn on/off, dim) */
1314
"commands-test": {
1415
host: "test-commands.example.com";
1516
protocol: "ws";
16-
description: "Test WebSocket server for commands (turn on/off, dim)";
1717
};
1818
"commands-prod": components["servers"]["commands-prod"];
1919
}
@@ -198,9 +198,9 @@ export interface operations {
198198
channels["lightTurnOff"]["messages"]["turnOff"]
199199
];
200200
reply: {
201+
/** @description Inline reply address extracted from message header */
201202
address: {
202203
location: "$message.header#/replyTo";
203-
description: "Inline reply address extracted from message header";
204204
};
205205
channel: channels["lightTurnOffDynamicReply"];
206206
messages: [
@@ -311,9 +311,9 @@ export interface components {
311311
reqid: string;
312312
};
313313
contentType: "application/json";
314+
/** @description Correlation ID. */
314315
correlationId: {
315316
location: "$message.header#/reqid";
316-
description: "Correlation ID.";
317317
};
318318
};
319319
/**
@@ -325,9 +325,9 @@ export interface components {
325325
payload?: components["schemas"]["measurementResponsePayload"];
326326
headers?: components["messageTraits"]["optionalReplyHeaders"]["headers"];
327327
contentType: "application/json";
328+
/** @description Correlation ID. */
328329
correlationId: {
329330
location: "$message.header#/reqid";
330-
description: "Correlation ID.";
331331
};
332332
};
333333
/**
@@ -344,9 +344,9 @@ export interface components {
344344
/** @description Correlation identifier for request/reply matching. */
345345
reqid: string;
346346
};
347+
/** @description Correlation ID. */
347348
correlationId: {
348349
location: "$message.header#/reqid";
349-
description: "Correlation ID.";
350350
};
351351
};
352352
/**
@@ -363,9 +363,9 @@ export interface components {
363363
/** @description Correlation identifier for request/reply matching. */
364364
reqid: string;
365365
};
366+
/** @description Correlation ID. */
366367
correlationId: {
367368
location: "$message.header#/reqid";
368-
description: "Correlation ID.";
369369
};
370370
};
371371
/**
@@ -416,28 +416,28 @@ export interface components {
416416
};
417417
};
418418
securitySchemes: {
419+
/** @description Bearer token authentication */
419420
bearerAuth: {
420421
type: "http";
421-
description: "Bearer token authentication";
422422
};
423423
};
424424
servers: {
425+
/** @description Test WebSocket server for events (lighting measurements) */
425426
"events-test": {
426427
host: "test-events.example.com";
427428
protocol: "ws";
428-
description: "Test WebSocket server for events (lighting measurements)";
429429
};
430+
/** @description Production WebSocket server for commands (turn on/off, dim) secured with TLS */
430431
"commands-prod": {
431432
host: "prod-commands.example.com";
432433
protocol: "wss";
433-
description: "Production WebSocket server for commands (turn on/off, dim) secured with TLS";
434434
};
435435
};
436436
messageTraits: {
437437
correlationId: {
438+
/** @description Correlation ID for request-reply matching, extracted from message header. */
438439
correlationId: {
439440
location: "$message.header#/reqid";
440-
description: "Correlation ID for request-reply matching, extracted from message header.";
441441
};
442442
};
443443
commonHeaders: {
@@ -465,19 +465,16 @@ export interface components {
465465
/** @description Reply address extracted from message header replyTo field */
466466
turnOnReplyAddress: {
467467
location: "$message.header#/replyTo";
468-
description: "Reply address extracted from message header replyTo field";
469468
};
470469
/** @description Reply address extracted from message payload responseAddress field */
471470
dimLightReplyAddress: {
472471
location: "$message.payload#/responseAddress";
473-
description: "Reply address extracted from message payload responseAddress field";
474472
};
475473
};
476474
correlationIds: {
477475
/** @description Request ID. */
478476
reqid: {
479477
location: "$message.header#/reqid";
480-
description: "Request ID.";
481478
};
482479
};
483480
}

‎packages/asyncapi-typescript-plugin/src/__snapshots__/with-asyncapi-types-file-name.ts.snapshot.ts‎

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@
55

66
export interface servers {
77
"events-test": components["servers"]["events-test"];
8+
/** @description Production WebSocket server for events (lighting measurements) secured with TLS */
89
"events-prod": {
910
host: "prod-events.example.com";
1011
protocol: "wss";
11-
description: "Production WebSocket server for events (lighting measurements) secured with TLS";
1212
};
13+
/** @description Test WebSocket server for commands (turn on/off, dim) */
1314
"commands-test": {
1415
host: "test-commands.example.com";
1516
protocol: "ws";
16-
description: "Test WebSocket server for commands (turn on/off, dim)";
1717
};
1818
"commands-prod": components["servers"]["commands-prod"];
1919
}
@@ -198,9 +198,9 @@ export interface operations {
198198
channels["lightTurnOff"]["messages"]["turnOff"]
199199
];
200200
reply: {
201+
/** @description Inline reply address extracted from message header */
201202
address: {
202203
location: "$message.header#/replyTo";
203-
description: "Inline reply address extracted from message header";
204204
};
205205
channel: channels["lightTurnOffDynamicReply"];
206206
messages: [
@@ -311,9 +311,9 @@ export interface components {
311311
reqid: string;
312312
};
313313
contentType: "application/json";
314+
/** @description Correlation ID. */
314315
correlationId: {
315316
location: "$message.header#/reqid";
316-
description: "Correlation ID.";
317317
};
318318
};
319319
/**
@@ -325,9 +325,9 @@ export interface components {
325325
payload?: components["schemas"]["measurementResponsePayload"];
326326
headers?: components["messageTraits"]["optionalReplyHeaders"]["headers"];
327327
contentType: "application/json";
328+
/** @description Correlation ID. */
328329
correlationId: {
329330
location: "$message.header#/reqid";
330-
description: "Correlation ID.";
331331
};
332332
};
333333
/**
@@ -344,9 +344,9 @@ export interface components {
344344
/** @description Correlation identifier for request/reply matching. */
345345
reqid: string;
346346
};
347+
/** @description Correlation ID. */
347348
correlationId: {
348349
location: "$message.header#/reqid";
349-
description: "Correlation ID.";
350350
};
351351
};
352352
/**
@@ -363,9 +363,9 @@ export interface components {
363363
/** @description Correlation identifier for request/reply matching. */
364364
reqid: string;
365365
};
366+
/** @description Correlation ID. */
366367
correlationId: {
367368
location: "$message.header#/reqid";
368-
description: "Correlation ID.";
369369
};
370370
};
371371
/**
@@ -416,28 +416,28 @@ export interface components {
416416
};
417417
};
418418
securitySchemes: {
419+
/** @description Bearer token authentication */
419420
bearerAuth: {
420421
type: "http";
421-
description: "Bearer token authentication";
422422
};
423423
};
424424
servers: {
425+
/** @description Test WebSocket server for events (lighting measurements) */
425426
"events-test": {
426427
host: "test-events.example.com";
427428
protocol: "ws";
428-
description: "Test WebSocket server for events (lighting measurements)";
429429
};
430+
/** @description Production WebSocket server for commands (turn on/off, dim) secured with TLS */
430431
"commands-prod": {
431432
host: "prod-commands.example.com";
432433
protocol: "wss";
433-
description: "Production WebSocket server for commands (turn on/off, dim) secured with TLS";
434434
};
435435
};
436436
messageTraits: {
437437
correlationId: {
438+
/** @description Correlation ID for request-reply matching, extracted from message header. */
438439
correlationId: {
439440
location: "$message.header#/reqid";
440-
description: "Correlation ID for request-reply matching, extracted from message header.";
441441
};
442442
};
443443
commonHeaders: {
@@ -465,19 +465,16 @@ export interface components {
465465
/** @description Reply address extracted from message header replyTo field */
466466
turnOnReplyAddress: {
467467
location: "$message.header#/replyTo";
468-
description: "Reply address extracted from message header replyTo field";
469468
};
470469
/** @description Reply address extracted from message payload responseAddress field */
471470
dimLightReplyAddress: {
472471
location: "$message.payload#/responseAddress";
473-
description: "Reply address extracted from message payload responseAddress field";
474472
};
475473
};
476474
correlationIds: {
477475
/** @description Request ID. */
478476
reqid: {
479477
location: "$message.header#/reqid";
480-
description: "Request ID.";
481478
};
482479
};
483480
}

‎packages/asyncapi-typescript-plugin/src/__snapshots__/with-enum-values.ts.snapshot.ts‎

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@
55

66
export interface servers {
77
"events-test": components["servers"]["events-test"];
8+
/** @description Production WebSocket server for events (lighting measurements) secured with TLS */
89
"events-prod": {
910
host: "prod-events.example.com";
1011
protocol: "wss";
11-
description: "Production WebSocket server for events (lighting measurements) secured with TLS";
1212
};
13+
/** @description Test WebSocket server for commands (turn on/off, dim) */
1314
"commands-test": {
1415
host: "test-commands.example.com";
1516
protocol: "ws";
16-
description: "Test WebSocket server for commands (turn on/off, dim)";
1717
};
1818
"commands-prod": components["servers"]["commands-prod"];
1919
}
@@ -198,9 +198,9 @@ export interface operations {
198198
channels["lightTurnOff"]["messages"]["turnOff"]
199199
];
200200
reply: {
201+
/** @description Inline reply address extracted from message header */
201202
address: {
202203
location: "$message.header#/replyTo";
203-
description: "Inline reply address extracted from message header";
204204
};
205205
channel: channels["lightTurnOffDynamicReply"];
206206
messages: [
@@ -311,9 +311,9 @@ export interface components {
311311
reqid: string;
312312
};
313313
contentType: "application/json";
314+
/** @description Correlation ID. */
314315
correlationId: {
315316
location: "$message.header#/reqid";
316-
description: "Correlation ID.";
317317
};
318318
};
319319
/**
@@ -325,9 +325,9 @@ export interface components {
325325
payload?: components["schemas"]["measurementResponsePayload"];
326326
headers?: components["messageTraits"]["optionalReplyHeaders"]["headers"];
327327
contentType: "application/json";
328+
/** @description Correlation ID. */
328329
correlationId: {
329330
location: "$message.header#/reqid";
330-
description: "Correlation ID.";
331331
};
332332
};
333333
/**
@@ -344,9 +344,9 @@ export interface components {
344344
/** @description Correlation identifier for request/reply matching. */
345345
reqid: string;
346346
};
347+
/** @description Correlation ID. */
347348
correlationId: {
348349
location: "$message.header#/reqid";
349-
description: "Correlation ID.";
350350
};
351351
};
352352
/**
@@ -363,9 +363,9 @@ export interface components {
363363
/** @description Correlation identifier for request/reply matching. */
364364
reqid: string;
365365
};
366+
/** @description Correlation ID. */
366367
correlationId: {
367368
location: "$message.header#/reqid";
368-
description: "Correlation ID.";
369369
};
370370
};
371371
/**
@@ -416,28 +416,28 @@ export interface components {
416416
};
417417
};
418418
securitySchemes: {
419+
/** @description Bearer token authentication */
419420
bearerAuth: {
420421
type: "http";
421-
description: "Bearer token authentication";
422422
};
423423
};
424424
servers: {
425+
/** @description Test WebSocket server for events (lighting measurements) */
425426
"events-test": {
426427
host: "test-events.example.com";
427428
protocol: "ws";
428-
description: "Test WebSocket server for events (lighting measurements)";
429429
};
430+
/** @description Production WebSocket server for commands (turn on/off, dim) secured with TLS */
430431
"commands-prod": {
431432
host: "prod-commands.example.com";
432433
protocol: "wss";
433-
description: "Production WebSocket server for commands (turn on/off, dim) secured with TLS";
434434
};
435435
};
436436
messageTraits: {
437437
correlationId: {
438+
/** @description Correlation ID for request-reply matching, extracted from message header. */
438439
correlationId: {
439440
location: "$message.header#/reqid";
440-
description: "Correlation ID for request-reply matching, extracted from message header.";
441441
};
442442
};
443443
commonHeaders: {
@@ -465,19 +465,16 @@ export interface components {
465465
/** @description Reply address extracted from message header replyTo field */
466466
turnOnReplyAddress: {
467467
location: "$message.header#/replyTo";
468-
description: "Reply address extracted from message header replyTo field";
469468
};
470469
/** @description Reply address extracted from message payload responseAddress field */
471470
dimLightReplyAddress: {
472471
location: "$message.payload#/responseAddress";
473-
description: "Reply address extracted from message payload responseAddress field";
474472
};
475473
};
476474
correlationIds: {
477475
/** @description Request ID. */
478476
reqid: {
479477
location: "$message.header#/reqid";
480-
description: "Request ID.";
481478
};
482479
};
483480
}

0 commit comments

Comments
 (0)