1
+
2
+ function generateDocstringsForBlueprint ( blueprint ) {
3
+ blueprint . routes . forEach ( route => {
4
+ console . log ( generateRouteDocstring ( route ) )
5
+ route . endpoints . forEach ( endpoint => {
6
+ console . log ( generateEndpointDocstring ( endpoint ) )
7
+ } )
8
+ route . subroutes . forEach ( subroute => {
9
+ console . log ( generateRouteDocstring ( subroute ) )
10
+ } )
11
+ } )
12
+ }
13
+
14
+ function generateRouteDocstring ( route ) {
15
+ const docstring = `
16
+ /**
17
+ * ${ route . name }
18
+ *
19
+ * Path: ${ route . path }
20
+ *
21
+ * Description: ${ route . description ?? "No description provided." }
22
+ *
23
+ * Namespace: ${ route . namespace !== '' ? route . namespace . name : "No namespace" }
24
+ *
25
+ * Endpoints:
26
+ * ${ route . endpoints . map ( endpoint => ` - ${ endpoint . name } : ${ endpoint . description } ` ) . join ( '\n' ) }
27
+ */`
28
+
29
+ return docstring
30
+ }
31
+
32
+ function generateEndpointDocstring ( endpoint ) {
33
+ const deprecationNotice = endpoint . isDeprecated === true ? ` (Deprecated: ${ endpoint . deprecationMessage } )` : ''
34
+
35
+ const docstring = `
36
+ /**
37
+ * ${ endpoint . name } ${ deprecationNotice }
38
+ *
39
+ * Path: ${ endpoint . path }
40
+ *
41
+ * Methods: ${ endpoint . methods . join ( ', ' ) }
42
+ *
43
+ * Description: ${ endpoint . description ?? "No description provided." }
44
+ *
45
+ * Parameters:
46
+ * ${ endpoint . parameters . map ( param => ` - ${ param . name } : ${ param . description } ${ param . isRequired === true ? ' (Required)' : '' } ` +
47
+ `${ param . isDeprecated === true ? ` (Deprecated: ${ param . deprecationMessage } )` : '' } ` ) . join ( '\n' ) }
48
+ *
49
+ * Request: ${ endpoint . request . semanticMethod !== '' ? `Semantic Method: ${ endpoint . request . semanticMethod } ` : "Not specified" }
50
+ *
51
+ * Response: ${ endpoint . response . description ?? "No description provided." }
52
+ */`
53
+
54
+ return docstring
55
+ }
56
+
57
+ const exampleRoute = {
58
+ name : "Get Devices" ,
59
+ path : "/devices" ,
60
+ description : "Retrieves a list of devices." ,
61
+ namespace : null ,
62
+ endpoints : [
63
+ {
64
+ name : "List Devices" ,
65
+ path : "/devices/list" ,
66
+ methods : [ "GET" ] ,
67
+ semanticMethod : "GET" ,
68
+ preferredMethod : "GET" ,
69
+ description : "Lists all devices." ,
70
+ isDeprecated : false ,
71
+ deprecationMessage : "" ,
72
+ parameters : [
73
+ { name : "limit" , isRequired : false , isDeprecated : false , deprecationMessage : "" , description : "What are endpoint parameters? How are they differnet from request params?" }
74
+ ] ,
75
+ request : {
76
+ methods : [ "GET" ] ,
77
+ semanticMethod : "GET" ,
78
+ preferredMethod : "GET" ,
79
+ parameters : [
80
+ { name : "limit" , isRequired : false , isDeprecated : false , deprecationMessage : "" , description : "Limit the number of devices returned." }
81
+ ]
82
+ } ,
83
+ response : {
84
+ description : "A list of devices."
85
+ }
86
+ }
87
+ ] ,
88
+ subroutes : [ ]
89
+ }
90
+
91
+ const blueprintExample = {
92
+ name : "Device API" ,
93
+ routes : [ exampleRoute ]
94
+ }
95
+
96
+ generateDocstringsForBlueprint ( blueprintExample )
0 commit comments