Docsmith CLI

Docsmith CLI is a Node.js command-line tool that automatically generates API documentation from your codebase. It scans your JavaScript files, extracts route definitions, and generates detailed markdown documentation, complete with example curl requests.

A Note from the Developer

This tool was initially developed for a personal project to automate the tedious task of generating API documentation. After realizing its potential, I've decided to release it publicly. While there are still issues to be addressed, I am committed to actively developing and improving this tool. Your feedback and contributions are welcome as I continue to refine its features and functionality.

Features

• Automatic Documentation Generation: Parses your codebase to extract API routes and generate comprehensive documentation.
• Enhanced Parameter Inference: Automatically infers parameter types from your code, making documentation more accurate and informative.
• Example Requests and Responses: Auto-generates example requests and responses for each API endpoint, helping users understand how to interact with your APIs.
• Real-time Documentation Updates: Watch mode allows you to automatically update documentation as you code, ensuring your docs are always up-to-date.
• Supports Custom Output: Documentation is generated in Markdown format by default, with future plans for additional formats.

Installation

You can install Docsmith CLI globally using npm:

npm install -g docsmith-cli

Or use it locally within your project:

npm install --save-dev docsmith-cli

Usage

Basic Command

To generate documentation, simply run the following command:

docsmith -i ./src -o ./API.md

This will scan the ./src directory and generate an API.md file in the project root.

New CLI Option: -e, --entry

You can now specify a main entry point file where routes are defined using the -e or --entry option. This option is particularly useful if your routes are defined in a single file.

docsmith -e ./src/index.js -o ./API.md

This command scans the ./src/index.js file and generates an API.md file.

Options

• -i, --input <directory>: Directory to scan for source files. Defaults to the current working directory.
• -e, --entry <file>: Main entry point file where routes are defined (e.g., main.js).
• -o, --output <file>: File to output the generated documentation. Defaults to generated-documentation.md.
• -w, --watch: Watch mode. Automatically regenerates documentation when files change.

Example

To generate documentation from an entry file and automatically update it when changes are made:

docsmith -e ./src/index.js -o ./API.md --watch

Example Output

The generated documentation will include:

• A table of contents linking to each API endpoint.
• Detailed information for each route, including HTTP method, path, parameters, and responses.
• Auto-generated example requests and responses for each endpoint.
• Example responses based on the actual code logic, where available.

Customization

You can customize the output format, add more features, or integrate this tool into your CI/CD pipeline for automated documentation updates. Future enhancements may include support for additional output formats such as HTML or PDF and integration with Swagger/OpenAPI specifications.

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request. We encourage you to help us make this tool even better.

To-Do

• [ ] Support for multiple output formats (HTML, PDF).
• [ ] Integration with Swagger/OpenAPI.
• [ ] Auto-generate example responses based on actual code logic.
• [ ] Extend support for more complex route definitions.
• [ ] Support for generating versioned documentation, allowing users to view documentation for different versions of the API.

Known Issues

• Path Parameter Inference: Currently, the tool assumes all path parameters are strings. If your API uses other types for path parameters, the inferred type may not be accurate.

• Status Code Detection: Status codes are extracted based on res.status() calls within route handlers. If your code sets status codes in a non-standard way or uses abstractions, these might not be detected correctly.

• Parameter Description Extraction: The tool tries to infer parameter descriptions from comments in the code, but it might miss descriptions if they are not in the expected format or are missing altogether.

• Incomplete Type Inference: While the tool attempts to infer parameter types based on usage within the code, it may not always be accurate, especially in complex cases where the type cannot be easily determined from the code.

• Limited Support for Complex Route Definitions: The tool currently focuses on standard route definitions. More complex routing logic, like dynamically generated routes or routes defined in external files not imported using standard require or import syntax, might not be processed correctly.

• Single Output Format: As of now, the tool only supports generating documentation in Markdown format. Support for additional formats like HTML or PDF is planned but not yet available.

• Large Codebases: For very large codebases, performance may degrade, and the tool might take longer to process all files and generate the documentation.

If you encounter any other issues, please report them here.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Special thanks to the open-source community for their tools and contributions that made this project possible. This tool was inspired by the need for keeping API documentation up-to-date and easily accessible.