jszy-swagger-doc-generator 1.1.0 → 1.1.1

package/README.md

@@ -1,73 +1,137 @@
-# Swagger Documentation Generator
+# jszy-swagger-doc-generator
 
 A tool to generate frontend documentation, TypeScript types, and React Hooks from Swagger/OpenAPI JSON files.
 
+## Features
+
+- Fetches Swagger JSON from a URL or loads from a local file
+- Generates comprehensive Markdown documentation
+- Generates TypeScript type definitions from schemas
+- Generates React Hooks for API endpoints, organized by tags
+- Supports both Swagger 2.0 and OpenAPI 3.x specifications
+- Handles API endpoints, parameters, request/response bodies, and responses
+- All generated content automatically placed in `./generated` directory to keep your project clean
+- Properly handles path and query parameters
+- Generates proper TypeScript interfaces and type aliases
+- Organizes generated code by API tags
+
 ## Installation
 
 You can install this package globally to use it as a CLI tool:
 
 ```bash
-npm install -g swagger-doc-generator
+npm install -g jszy-swagger-doc-generator
 ```
 
 Or you can use it without installing with npx:
 
 ```bash
-npx swagger-doc-generator
+npx jszy-swagger-doc-generator
 ```
 
-## Usage
+## Usage Examples
 
-### Command Line Interface
+### Example 1: Generate docs from a local Swagger JSON file
 
-The tool can be used from the command line to generate documentation, TypeScript types, or React Hooks from a Swagger JSON file:
+1. First, make sure you have a swagger.json file in your project
+2. Run the command:
+```bash
+jszy-swagger-doc-generator --input ./swagger.json
+```
+3. Check the generated documentation in `./generated/docs/api-documentation.md`
 
-#### Generate Documentation (Default)
+### Example 2: Generate from a live API endpoint
+
+1. If your API is running and exposes Swagger JSON at `http://localhost:3000/api-docs-json`:
 ```bash
-# Generate documentation from a URL (output to ./generated/docs/api-documentation.md by default)
-swagger-doc-generator --url https://petstore.swagger.io/v2/swagger.json
+jszy-swagger-doc-generator --url http://localhost:3000/api-docs-json
+```
+2. All content will be generated in the `./generated` directory by default
 
-# Generate documentation from a local file (output to ./generated/docs/api-documentation.md by default)
-swagger-doc-generator --input ./swagger.json
+### Example 3: Generate TypeScript types and React hooks
 
-# Generate documentation and specify output file
-swagger-doc-generator --url https://petstore.swagger.io/v2/swagger.json --output ./docs/api-documentation.md
+1. To generate TypeScript types and React hooks from your Swagger file:
+```bash
+jszy-swagger-doc-generator --input ./swagger.json --generate-types --generate-hooks
 ```
+2. Generated files will be in:
+   - TypeScript types: `./generated/types/`
+   - React hooks: `./generated/hooks/`
+
+### Example 4: Generate everything from a URL
 
-#### Generate TypeScript Types
+1. Generate all documentation, types, and hooks from a live API:
 ```bash
-# Generate TypeScript types from a local file (output to ./generated/types/ by default)
-swagger-doc-generator --input ./swagger.json --generate-types
+jszy-swagger-doc-generator --url http://localhost:3000/api-docs-json --generate-types --generate-hooks
+```
+2. This will create all outputs in the `./generated` directory
+
+## CLI Options
 
-# Generate TypeScript types with custom output directory
-swagger-doc-generator --input ./swagger.json --generate-types --types-output ./src/types
+- `--url, -u`: URL to the Swagger JSON file
+- `--input, -i`: Path to the local Swagger JSON file
+- `--output, -o`: Output path for the generated documentation (default: ./generated/docs/api-documentation.md)
+- `--generate-types`: Generate TypeScript type definitions
+- `--generate-hooks`: Generate React hooks
+- `--types-output`: Output directory for TypeScript types (default: ./generated/types)
+- `--hooks-output`: Output directory for React hooks (default: ./generated/hooks)
+- `--help`: Show help information
+
+## Generated Output Structure
+
+By default, all generated content goes to the `./generated` directory:
+
+```
+generated/
+├── docs/
+│   └── api-documentation.md
+├── types/
+│   └── [generated TypeScript types]
+└── hooks/
+    ├── user/
+    ├── config/
+    └── [other tags as directories]/
 ```
 
-#### Generate React Hooks
-```bash
-# Generate React hooks from a local file (output to ./generated/hooks/ by default)
-swagger-doc-generator --input ./swagger.json --generate-hooks
+## Using Generated TypeScript Types
+
+Once generated, the TypeScript types can be imported in your project:
 
-# Generate React hooks with custom output directory
-swagger-doc-generator --input ./swagger.json --generate-hooks --hooks-output ./src/hooks
+```typescript
+import { User, UserConfig } from './generated/types/your-api-types';
 
-# Generate both types and hooks (output to ./generated/ directories by default)
-swagger-doc-generator --input ./swagger.json --generate-types --generate-hooks
+const user: User = {
+  id: 1,
+  name: 'John Doe',
+  email: 'john@example.com'
+};
 ```
 
-#### Default Output Location
-By default, all generated content is placed in the `./generated` directory to keep your project clean and separate generated content from source code:
+## Using Generated React Hooks
 
-- Documentation: `./generated/docs/api-documentation.md`
-- TypeScript types: `./generated/types/`
-- React hooks: `./generated/hooks/`
+The generated React hooks can be used in your React components:
 
-### Programmatic Usage
+```typescript
+import { useUserController_queryUserInfo } from './generated/hooks/users/users.hooks';
+
+function MyComponent() {
+  const { userController_queryUserInfo } = useUserController_queryUserInfo();
+  
+  const fetchUser = async () => {
+    const user = await userController_queryUserInfo({ id: 1 });
+    console.log(user);
+  };
+  
+  return <button onClick={fetchUser}>Fetch User</button>;
+}
+```
+
+## Programmatic Usage
 
 You can also use this package programmatically in your JavaScript/TypeScript code:
 
 ```javascript
-const { SwaggerDocGenerator } = require('swagger-doc-generator');
+const { SwaggerDocGenerator } = require('jszy-swagger-doc-generator');
 
 async function generate() {
   const generator = new SwaggerDocGenerator();
@@ -94,91 +158,6 @@ async function generate() {
 generate().catch(console.error);
 ```
 
-## Options
-
-- `--url, -u`: URL to the Swagger JSON file
-- `--input, -i`: Path to the local Swagger JSON file
-- `--output, -o`: Output path for the generated documentation (default: ./docs/api-documentation.md)
-- `--generate-types`: Generate TypeScript type definitions
-- `--generate-hooks`: Generate React hooks
-- `--types-output`: Output directory for TypeScript types (default: ./types)
-- `--hooks-output`: Output directory for React hooks (default: ./hooks)
-- `--help`: Show help information
-
-## Features
-
-- Fetches Swagger JSON from a URL
-- Loads Swagger JSON from a local file
-- Generates comprehensive documentation in Markdown format
-- Generates TypeScript type definitions from schemas
-- Generates React Hooks for API endpoints, organized by tags
-- Supports both Swagger 2.0 and OpenAPI 3.x specifications
-- Handles API endpoints, parameters, request/response bodies, and responses
-- Creates output directory if it doesn't exist
-- Properly handles path and query parameters
-- Generates proper TypeScript interfaces and type aliases
-- Organizes generated code by API tags
-
-## Example Output
-
-### Generated TypeScript Types
-```typescript
-// Auto-generated TypeScript types from Swagger schema
-
-export interface User {
-  /** 用户ID */
-  id: number;
-  /** 用户名 */
-  name: string;
-  /** 用户邮箱 */
-  email: string;
-  /** 头像URL */
-  avatar?: string;
-}
-
-export interface UserConfig {
-  /** 用户ID */
-  userId: number;
-  /** 主题设置 */
-  theme: "light" | "dark";
-  /** 语言设置 */
-  language: string;
-  /** 通知设置 */
-  notifications: NotificationSettings;
-  /** 个性化设置 */
-  preferences: Preferences;
-}
-```
-
-### Generated React Hooks
-```typescript
-// Users API Hooks
-
-export interface UserController_queryUserInfoParams {
-  id?: number;
-  name?: string;
-}
-
-export const useUserController_queryUserInfo = () => {
-  const apiCall = async (params: UserController_queryUserInfoParams) => {
-    const path = `${process.env.REACT_APP_API_BASE_URL || ''}/api/queryUserInfo`;
-    const queryParams = new URLSearchParams();
-    if (params.id) queryParams.append('id', params.id.toString());
-    if (params.name) queryParams.append('name', params.name.toString());
-    const queryString = queryParams.toString();
-    const url = `${path}${queryString ? '?' + queryString : ''}`;
-    const options: RequestInit = {
-      method: 'GET',
-    };
-
-    const result = await fetch(url, options);
-    return result.json() as Promise<User[]>;
-  };
-
-  return { userController_queryUserInfo: apiCall };
-};
-```
-
 ## Development
 
 To run this project locally:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jszy-swagger-doc-generator",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A tool to generate frontend documentation from Swagger/OpenAPI JSON files",
   "main": "dist/index.js",
   "bin": {