jszy-swagger-doc-generator 1.1.1 → 1.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -6
- package/dist/cli.js +17 -5
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +44 -12
- package/dist/index.js +394 -70
- package/dist/index.js.map +1 -1
- package/package.json +6 -3
- package/src/cli.ts +21 -5
- package/src/index.ts +432 -78
package/README.md
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
# jszy-swagger-doc-generator
|
|
1
|
+
# jszy-swagger-doc-generator (api-sdk)
|
|
2
2
|
|
|
3
3
|
A tool to generate frontend documentation, TypeScript types, and React Hooks from Swagger/OpenAPI JSON files.
|
|
4
4
|
|
|
5
|
+
Available command aliases: `api-sdk`, `jszy-swagger-doc-generator`, `swagger-doc-generator`
|
|
6
|
+
|
|
5
7
|
## Features
|
|
6
8
|
|
|
7
9
|
- Fetches Swagger JSON from a URL or loads from a local file
|
|
@@ -34,9 +36,13 @@ npx jszy-swagger-doc-generator
|
|
|
34
36
|
### Example 1: Generate docs from a local Swagger JSON file
|
|
35
37
|
|
|
36
38
|
1. First, make sure you have a swagger.json file in your project
|
|
37
|
-
2. Run the command:
|
|
39
|
+
2. Run the command using the primary alias:
|
|
40
|
+
```bash
|
|
41
|
+
api-sdk --input ./swagger.json
|
|
42
|
+
```
|
|
43
|
+
Alternatively, you can use the full package name:
|
|
38
44
|
```bash
|
|
39
|
-
jszy-swagger-doc-generator --input ./swagger.json
|
|
45
|
+
npx jszy-swagger-doc-generator --input ./swagger.json
|
|
40
46
|
```
|
|
41
47
|
3. Check the generated documentation in `./generated/docs/api-documentation.md`
|
|
42
48
|
|
|
@@ -44,7 +50,7 @@ jszy-swagger-doc-generator --input ./swagger.json
|
|
|
44
50
|
|
|
45
51
|
1. If your API is running and exposes Swagger JSON at `http://localhost:3000/api-docs-json`:
|
|
46
52
|
```bash
|
|
47
|
-
|
|
53
|
+
api-sdk --url http://localhost:3000/api-docs-json
|
|
48
54
|
```
|
|
49
55
|
2. All content will be generated in the `./generated` directory by default
|
|
50
56
|
|
|
@@ -52,7 +58,7 @@ jszy-swagger-doc-generator --url http://localhost:3000/api-docs-json
|
|
|
52
58
|
|
|
53
59
|
1. To generate TypeScript types and React hooks from your Swagger file:
|
|
54
60
|
```bash
|
|
55
|
-
|
|
61
|
+
api-sdk --input ./swagger.json --generate-types --generate-hooks
|
|
56
62
|
```
|
|
57
63
|
2. Generated files will be in:
|
|
58
64
|
- TypeScript types: `./generated/types/`
|
|
@@ -62,12 +68,15 @@ jszy-swagger-doc-generator --input ./swagger.json --generate-types --generate-ho
|
|
|
62
68
|
|
|
63
69
|
1. Generate all documentation, types, and hooks from a live API:
|
|
64
70
|
```bash
|
|
65
|
-
|
|
71
|
+
api-sdk --url http://localhost:3000/api-docs-json --generate-types --generate-hooks
|
|
66
72
|
```
|
|
67
73
|
2. This will create all outputs in the `./generated` directory
|
|
68
74
|
|
|
69
75
|
## CLI Options
|
|
70
76
|
|
|
77
|
+
The tool provides multiple command aliases: `api-sdk`, `jszy-swagger-doc-generator`, and `swagger-doc-generator`.
|
|
78
|
+
All commands support the same options:
|
|
79
|
+
|
|
71
80
|
- `--url, -u`: URL to the Swagger JSON file
|
|
72
81
|
- `--input, -i`: Path to the local Swagger JSON file
|
|
73
82
|
- `--output, -o`: Output path for the generated documentation (default: ./generated/docs/api-documentation.md)
|
package/dist/cli.js
CHANGED
|
@@ -92,11 +92,11 @@ const argv = (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
|
|
|
92
92
|
.parseSync();
|
|
93
93
|
async function run() {
|
|
94
94
|
try {
|
|
95
|
-
//
|
|
95
|
+
// Clean the entire generated directory before doing anything
|
|
96
96
|
const generatedDir = './generated';
|
|
97
|
-
if (
|
|
98
|
-
fs.
|
|
99
|
-
console.log(`
|
|
97
|
+
if (fs.existsSync(generatedDir)) {
|
|
98
|
+
fs.rmSync(generatedDir, { recursive: true, force: true });
|
|
99
|
+
console.log(`Cleared generated directory: ${generatedDir}`);
|
|
100
100
|
}
|
|
101
101
|
const generator = new index_1.SwaggerDocGenerator();
|
|
102
102
|
let swaggerDoc;
|
|
@@ -117,6 +117,10 @@ async function run() {
|
|
|
117
117
|
}
|
|
118
118
|
// Check if we need to generate types
|
|
119
119
|
if (argv.generateTypes) {
|
|
120
|
+
// Create the generated directory if it doesn't exist
|
|
121
|
+
if (!fs.existsSync(generatedDir)) {
|
|
122
|
+
fs.mkdirSync(generatedDir, { recursive: true });
|
|
123
|
+
}
|
|
120
124
|
console.log('Generating TypeScript type definitions...');
|
|
121
125
|
const types = generator.generateTypeDefinitions(swaggerDoc);
|
|
122
126
|
const typesOutputPath = argv.typesOutput.endsWith('.ts') ? argv.typesOutput :
|
|
@@ -126,13 +130,21 @@ async function run() {
|
|
|
126
130
|
}
|
|
127
131
|
// Check if we need to generate hooks
|
|
128
132
|
if (argv.generateHooks) {
|
|
133
|
+
// Create the generated directory if it doesn't exist
|
|
134
|
+
if (!fs.existsSync(generatedDir)) {
|
|
135
|
+
fs.mkdirSync(generatedDir, { recursive: true });
|
|
136
|
+
}
|
|
129
137
|
console.log('Generating React hooks...');
|
|
130
138
|
const hooksByTag = generator.generateReactHooks(swaggerDoc);
|
|
131
139
|
generator.saveHooksByTag(hooksByTag, argv.hooksOutput);
|
|
132
|
-
console.log(`React hooks generated successfully in: ${argv.hooksOutput}/`);
|
|
140
|
+
console.log(`React hooks and types generated successfully in: ${argv.hooksOutput}/`);
|
|
133
141
|
}
|
|
134
142
|
// Generate documentation if not generating types or hooks (for backward compatibility)
|
|
135
143
|
if (!argv.generateTypes && !argv.generateHooks) {
|
|
144
|
+
// Create the generated directory if it doesn't exist
|
|
145
|
+
if (!fs.existsSync(generatedDir)) {
|
|
146
|
+
fs.mkdirSync(generatedDir, { recursive: true });
|
|
147
|
+
}
|
|
136
148
|
console.log('Generating documentation...');
|
|
137
149
|
const documentation = generator.generateDocumentation(swaggerDoc);
|
|
138
150
|
generator.saveDocumentationToFile(documentation, argv.output);
|
package/dist/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,mCAA0D;AAC1D,kDAA0B;AAC1B,2CAAwC;AACxC,uCAAyB;
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -93,35 +93,64 @@ export declare class SwaggerDocGenerator {
|
|
|
93
93
|
[key: string]: any;
|
|
94
94
|
}): string;
|
|
95
95
|
/**
|
|
96
|
-
* Generates React hooks from the paths in Swagger doc
|
|
96
|
+
* Generates React hooks from the paths in Swagger doc organized by tag
|
|
97
97
|
*/
|
|
98
|
-
generateReactHooks(swaggerDoc: SwaggerDoc): Map<string,
|
|
98
|
+
generateReactHooks(swaggerDoc: SwaggerDoc): Map<string, {
|
|
99
|
+
hooks: string;
|
|
100
|
+
types: string;
|
|
101
|
+
}>;
|
|
99
102
|
/**
|
|
100
|
-
*
|
|
103
|
+
* Checks if a schema is used in any of the endpoints
|
|
101
104
|
*/
|
|
102
|
-
|
|
105
|
+
isSchemaUsedInEndpoints(schemaName: string, endpoints: Array<{
|
|
106
|
+
path: string;
|
|
107
|
+
method: string;
|
|
108
|
+
endpointInfo: any;
|
|
109
|
+
}>, allSchemas: {
|
|
110
|
+
[key: string]: any;
|
|
111
|
+
}): boolean;
|
|
103
112
|
/**
|
|
104
|
-
*
|
|
113
|
+
* Checks if a schema contains a reference to another schema
|
|
105
114
|
*/
|
|
106
|
-
|
|
115
|
+
schemaContainsRef(schema: any, targetSchemaName: string, allSchemas: {
|
|
107
116
|
[key: string]: any;
|
|
108
|
-
}):
|
|
117
|
+
}): boolean;
|
|
118
|
+
/**
|
|
119
|
+
* Find all referenced schemas from a set of directly used schemas
|
|
120
|
+
*/
|
|
121
|
+
findAllReferencedSchemas(initialSchemas: Set<string>, allSchemas: {
|
|
122
|
+
[key: string]: any;
|
|
123
|
+
}): Set<string>;
|
|
124
|
+
/**
|
|
125
|
+
* Find schema references in a given schema
|
|
126
|
+
*/
|
|
127
|
+
findSchemaReferences(schema: any, allSchemas: {
|
|
128
|
+
[key: string]: any;
|
|
129
|
+
}): Set<string>;
|
|
109
130
|
/**
|
|
110
|
-
* Generates a
|
|
131
|
+
* Generates a parameter interface for an API endpoint
|
|
111
132
|
*/
|
|
112
|
-
|
|
133
|
+
generateParamInterface(path: string, method: string, endpointInfo: any, schemas: {
|
|
113
134
|
[key: string]: any;
|
|
114
135
|
}): string;
|
|
115
136
|
/**
|
|
116
|
-
* Generates a
|
|
137
|
+
* Generates a React Query hook using axios
|
|
117
138
|
*/
|
|
118
|
-
|
|
139
|
+
generateReactQueryHook(path: string, method: string, endpointInfo: any, schemas: {
|
|
119
140
|
[key: string]: any;
|
|
120
141
|
}): string;
|
|
121
142
|
/**
|
|
122
143
|
* Generate operation ID from path and method if not provided
|
|
123
144
|
*/
|
|
124
145
|
generateOperationId(path: string, method: string): string;
|
|
146
|
+
/**
|
|
147
|
+
* Formats code using Prettier - sync version with child process
|
|
148
|
+
*/
|
|
149
|
+
private formatCode;
|
|
150
|
+
/**
|
|
151
|
+
* Gets the parser based on file extension
|
|
152
|
+
*/
|
|
153
|
+
private getParserForFile;
|
|
125
154
|
/**
|
|
126
155
|
* Saves the generated documentation to a file
|
|
127
156
|
*/
|
|
@@ -133,5 +162,8 @@ export declare class SwaggerDocGenerator {
|
|
|
133
162
|
/**
|
|
134
163
|
* Saves the generated React hooks to files organized by tag
|
|
135
164
|
*/
|
|
136
|
-
saveHooksByTag(hooksByTag: Map<string,
|
|
165
|
+
saveHooksByTag(hooksByTag: Map<string, {
|
|
166
|
+
hooks: string;
|
|
167
|
+
types: string;
|
|
168
|
+
}>, outputDir: string): void;
|
|
137
169
|
}
|