Skip to main content

Generating API Documentation and Config

The devdocs.generateAPIDocumentation command allows you to generate API documentation and configuration files directly from your codebase. It analyzes your code, identifies API routes, and generates a Postman Collection JSON file containing all the detected API routes. Additionally, it can generate an OpenAPI (Swagger) specification file for your API.

Why Should I Use This VS Code Extension Command?​

Generating API documentation from your codebase has several advantages:


  1. Keeps Documentation Synchronized with Code: By generating documentation directly from your code, you ensure that your API documentation stays up-to-date with the latest changes in your codebase, reducing the risk of documentation drift.

  2. Saves Time and Effort: Manually documenting APIs can be a time-consuming and error-prone process. This command automates the process, saving you valuable time and effort.

  3. Improves Developer Experience: Well-documented APIs enhance the developer experience by providing a clear understanding of the available endpoints, request/response formats, and other details, making it easier for developers to integrate with and consume your API.

  4. Facilitates Testing and Collaboration: The generated Postman Collection can be used for testing and sharing API documentation with team members or external partners, promoting collaboration and ensuring everyone is working with the same API specifications.

What Are Relevant Configuration Options in the dev-docs.json?​

The following configuration options in the dev-docs.json file are relevant for the devdocs.generateAPIDocumentation command:


  • ai.openapi.file: Specifies the file path where the generated OpenAPI specification file should be saved.

Example JSON of Relevant dev-docs.json Options​

{
  "ai": {
    "openapi": {
      "file": "src/api/openapi.yaml"
    }
  }
}

Prerequisites​

  1. Your project should have a dev-docs.json configuration file in the root directory.
  2. The dev-docs.json file should be properly configured with the relevant options mentioned above.

How Do I Use This VS Code Extension Command?​

  1. Open the command palette: Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) to open the command palette.
  2. Search for the command: Type devdocs.generateAPIDocumentation and select it from the list.
  3. Wait for the generation process: The extension will analyze your codebase, identify API routes, and generate the Postman Collection JSON file and OpenAPI specification file based on your configuration.
  4. Review the generated files: Once the process is complete, you can find the generated files in the locations specified in your dev-docs.json configuration.

The generated Postman Collection JSON file can be imported into Postman or other compatible tools for testing and documentation purposes. The OpenAPI specification file can be used for generating client libraries, documentation, or integrating with other tools that support the OpenAPI standard.


By following this process, you can ensure that your API documentation stays up-to-date with your codebase, improving developer experience and facilitating collaboration within your team or with external partners.

Dev-Docs AI Bot

Circular button