API Tutorials - SmartGen Docs

APIs (Application Programming Interfaces) are the backbone of modern software, enabling different systems to communicate and share data. Documenting your APIs clearly and comprehensively is crucial for developers who need to integrate with your services. SmartGen Docs provides robust features to help you create professional and user-friendly API documentation.

This tutorial will guide you through the process of integrating and documenting APIs within your SmartGen Docs project, covering everything from generating API references to best practices for writing clear and effective API guides.

1. Understanding API Documentation Needs

Effective API documentation typically addresses several key areas:

Overview: What does the API do? What problems does it solve?
Authentication: How do users gain access to the API (e.g., API keys, OAuth2)?
Endpoints: A list of available API resources, their methods (GET, POST, PUT, DELETE), and expected request/response formats.
Request/Response Examples: Clear examples of how to make requests and what responses to expect.
Error Handling: A comprehensive list of error codes and their meanings.
Rate Limits: Information on usage limits to prevent abuse.
SDKs/Libraries: Links to client libraries that simplify API interaction.
Webhooks: How to set up and receive automated notifications.

SmartGen Docs can help you structure and present all this information effectively.

2. Generating API Reference with Autodoc (for Python APIs)

If your API is built with Python, the autodoc plugin can automatically generate much of your API reference documentation directly from your code.

Steps:

Enable and Configure Autodoc: Ensure the autodoc plugin is enabled and configured in your smartgen.yml to point to your API`s source code and desired output directory. (Refer to the Autodoc Guide for detailed setup).
```
plugins:
  - autodoc:
      source_dir: my_api_project/src
      output_dir: api/reference
```
Document Your Code: Write clear and comprehensive docstrings for your API functions, classes, and methods in your Python code. Use a consistent style (e.g., Sphinx, Google).
Run Build Command: Execute smartgen-docs build to generate the Markdown files for your API reference.
```
smartgen-docs build
```

Integrate into Navigation: Add the generated Markdown files to your nav section in smartgen.yml.

nav:
  - API Reference:
      - Overview: api/index.md
      - Authentication: api/authentication.md
      - Endpoints: api/endpoints.md
      - API Modules:
          - My API Module: api/reference/my_api_project.module_name.md

3. Manually Documenting REST APIs and Webhooks

For non-Python APIs, or for sections like authentication, error codes, and webhooks that require more narrative explanation, you will write Markdown files manually.

Example: Documenting an API Endpoint (`docs/api/endpoints.md`)

---
title: API Endpoints - SmartGen Docs
description: Detailed documentation for all available API endpoints in SmartGen Docs, including methods, parameters, and example requests/responses.
keywords: API endpoints, REST API, SmartGen Docs API, GET, POST, PUT, DELETE
---

# API Endpoints

This section provides a comprehensive list of all available API endpoints for the SmartGen Platform, detailing their functionality, required parameters, and expected responses.

## Base URL

All API requests should be prefixed with the following base URL:

`https://api.smartgentools.com/v1`

## Authentication

All endpoints require authentication. Please refer to the [Authentication Guide](../api/authentication.md) for details on how to obtain and use your API key.

## 1. Get All Projects

Retrieves a list of all projects associated with your account.

*   **Endpoint**: `/projects`
*   **Method**: `GET`
*   **Authentication**: Required (API Key)

### Request

```bash
curl -X GET \
  https://api.smartgentools.com/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

[
  {
    "id": "proj_abc123",
    "name": "My First Project",
    "created_at": "2026-07-21T10:00:00Z"
  },
  {
    "id": "proj_xyz789",
    "name": "Marketing Campaign Docs",
    "created_at": "2026-07-20T15:30:00Z"
  }
]

2. Create New Project

Creates a new project.

Endpoint: /projects
Method: POST
Authentication: Required (API Key)

Request

curl -X POST \
  https://api.smartgentools.com/v1/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d

Response (201 Created)

{
  "id": "proj_new456",
  "name": "New Project Title",
  "created_at": "2026-07-21T11:00:00Z"
}

4. Best Practices for API Documentation

Clarity and Conciseness: Use clear, unambiguous language. Get straight to the point.
Consistency: Maintain a consistent structure, terminology, and style across all API documentation.
Examples: Provide practical code examples in multiple languages (if applicable) for every endpoint. This is invaluable for developers.
Interactive Elements: Consider using tools like OpenAPI/Swagger UI to provide interactive API explorers (though this might require custom integration with SmartGen Docs).
Error Handling: Document all possible error codes, their meanings, and how developers should handle them.
Version Control: Keep your API documentation under version control alongside your API code.
Regular Updates: Ensure your documentation is updated whenever your API changes. Outdated documentation is worse than no documentation.

By following these guidelines, you can create API documentation that is a pleasure to use and significantly reduces the learning curve for developers integrating with your SmartGen Platform APIs.