ngDoc - API

Generating API Documentation in Angular Applications

This document outlines how to automatically generate API documentation within your Angular applications. We’ll leverage @ng-doc/builder and @ng-doc/core to streamline this process.

1. Installation

To begin, install the @ng-doc/builder package using the Angular CLI. This builder facilitates the API documentation generation.

ng add @ng-doc/builder

2. Model File Creation

Define the model files that you want to include in your API documentation. For instance, create a sample.model.ts file with the following structure:

export interface ISample {
  key: string;
  value: string;
}

export interface ISam {
  key: string;
  value: string;
}

export enum TEST {
  NONE = 0,
  ONE = 1,
  TWO = 2
}

export type TType = {
  key: string;
  value: string;
}

This file defines interfaces, enums, and types that will be reflected in your API documentation.

3. API Configuration File Creation

Create an API configuration file (e.g., ng-doc.api.ts) to configure the documentation generation process. This configuration is utilized by @ng-doc/core.

import { NgDocApi } from '@ng-doc/core';
import GettingStartedCategory from './getting-started/ng-doc.category';

const Api: NgDocApi = {
  title: 'API Documentation',
  category: GettingStartedCategory,
  scopes: [
    {
      name: 'example-library', // Scope name
      route: 'examlibrary', // Route path
      include: 'src/app/sample.model.ts', // Model file path to include
    },
  ],
};

export default Api;

Within the scopes array, specify the paths to your model files and other relevant information for documentation generation. Each scope represents a distinct section in your API documentation.

4. API Documentation Generation

After creating the API configuration file and completing the settings, execute the following command to generate the API documentation:

ng generate @ng-doc/builder:api

This command triggers the @ng-doc/builder to parse your code and generate the documentation based on your configuration.

5. Verification

Once the API documentation is generated, you can access it within your Angular application. For example, navigate to http://localhost:4200/api/examlibrary in your browser to view the API documentation.

The generated API documentation automatically lists information related to the model files you’ve defined. This approach extends beyond interfaces; you can also document services, components, and other elements in a similar manner.

By following these steps, you can effectively manage and provide comprehensive API documentation for your Angular applications, benefiting developers and promoting code maintainability.