Creating API Documentation

Creating API Documentation Using the ApiDoc Class

Home documentation

In our project, we use the ApiDoc class to create documentation for the API endpoints in our routing system. This allows us to generate OpenAPI/Swagger-compliant documentation, making it easier for developers to understand and interact with our API.

Overview of the ApiDoc Class

The ApiDoc class is designed to represent the documentation for an API endpoint, including parameters, request body fields, responses, and descriptions for different HTTP methods such as GET, POST, PUT, and DELETE. Each endpoint can be documented with details on how it should be used, what parameters it accepts, and what responses it can return.

Example: Defining API Documentation for Routes

Let's look at how you can use the ApiDoc class to document your API endpoints. Here’s an example where we define documentation for a service-related API.

Defining API Documentation

class ApiDocuments {
  // Documentation for the 'List Services' API endpoint.
  static Future<ApiDoc> serviceList() async {
    return ApiDoc(
      response: {
        '403': r_403, // Response for unauthorized access.
        '200': [      // Response for successful retrieval of services.
          ApiResponse<int>('timestamp_start', def: 12345),
          ApiResponse<bool>('success', def: true),
          ApiResponse<List<ServiceModel>>(
            'data',
            def: [await ServiceModel().toParams()],
          ),
          ApiResponse<Map>('pagin', def: {}),
        ],
      },
    );
  }

  // Documentation for the 'Get One Service' API endpoint.
  static Future<ApiDoc> oneService() async {
    return ApiDoc(
      parameters: [ApiParameter('id', paramIn: ParamIn.path)], // Path parameter 'id'.
      response: {
        '403': r_403, // Response for unauthorized access.
        '404': r_404, // Response for service not found.
        '200': [      // Response for successful retrieval of a service.
          ApiResponse<int>('timestamp_start', def: 12345),
          ApiResponse<bool>('success', def: true),
          ApiResponse<ServiceModel>(
            'data',
            def: await ServiceModel().toParams(),
          ),
        ],
      },
    );
  }
}

In this example, we define two API documentation methods:

1. serviceList: Describes an endpoint that lists services, with responses for success (200) and unauthorized access (403).
2. oneService: Describes an endpoint that retrieves a single service by its id, with responses for success (200), unauthorized access (403), and not found (404).

Integrating API Documentation with Routing

Once the API documentation is defined, you can integrate it into your routing setup using the WebRoute class.

WebRoute(
  path: 'services/',
  methods: RequestMethods.ONLY_GET,
  index: serviceController.serviceList,
  apiDoc: ApiDocuments.serviceList,  // Attach the API documentation
  permissions: [Permissions.superAdmin],
  auth: authController,
  rq: rq,
),
WebRoute(
  path: 'services/{id}',
  methods: RequestMethods.ONLY_GET,
  index: serviceController.oneService,
  apiDoc: ApiDocuments.oneService,  // Attach the API documentation
  permissions: [Permissions.superAdmin],
  auth: authController,
  rq: rq,
),

In this setup:

• The apiDoc parameter is used to attach the relevant API documentation to each route.
• When a developer navigates through these routes, they can easily refer to the attached documentation to understand the expected inputs and outputs.

Exposing API Documentation via an Endpoint

Finally, you can create a route to expose the generated API documentation, making it accessible via a web interface.

WebRoute(
  path: 'doc',
  extraPath: ['v1/doc'],
  rq: rq,
  methods: RequestMethods.ONLY_GET,
  controller: documents,
  index: () => documents.index(showPublic: false),  // Generates and serves the documentation
),

This route provides an endpoint (/doc) where the entire API documentation can be viewed. When accessed, this will display the documentation in a format that is typically rendered as a Swagger UI or similar, making it user-friendly and interactive.

Summary

By leveraging the ApiDoc class, you can:

1. Create detailed documentation for each API endpoint in your project.
2. Integrate this documentation with your routing system, ensuring that each route is accompanied by comprehensive usage instructions.
3. Expose the documentation via a dedicated endpoint, allowing it to be viewed through a web interface.

This approach not only improves the maintainability of your code but also enhances the developer experience by providing clear and accessible API documentation.