# API Module

## Overview

The API module contains all Swagger documentation files for the dataflow-service project, used to describe and display the API interfaces of various services. These Swagger files can be used to generate client code, API documentation, and testing tools.

## Directory Structure

```
api/
├── agent.swagger.json           # API documentation for Agent service
├── backup.swagger.json          # API documentation for Backup service
├── changefeed.swagger.json      # API documentation for Change Data Capture service
├── dataflow.swagger.json        # API documentation for main service
├── dm.swagger.json              # API documentation for Data Migration service
├── import_into.swagger.json     # API documentation for Data Import service
├── import_into.ui.swagger.json  # UI-specific API documentation for Data Import service
├── premium_dm.swagger.json      # API documentation for Premium Data Migration service
├── premium_dm.ui.swagger.json   # UI-specific API documentation for Premium Data Migration service
├── README.md                    # This file
├── recovery-group-v1beta1.swagger.json  # API documentation for Recovery Group service
└── service.swagger.json         # API documentation for common services
```

## File Description

| File Name | Description |
|--------|------|
| agent.swagger.json | Describes the API interfaces of the Agent service, used to communicate with Agents deployed in various environments |
| backup.swagger.json | Describes the API interfaces of the Backup service, used to create, manage, and monitor backup tasks |
| changefeed.swagger.json | Describes the API interfaces of the Change Data Capture service, used to create and manage data change synchronization tasks |
| dataflow.swagger.json | Describes the API interfaces of the main service, including aggregated APIs from various sub-services |
| dm.swagger.json | Describes the API interfaces of the Data Migration service, used to migrate data from other database systems to TiDB |
| import_into.swagger.json | Describes the API interfaces of the Data Import service, used to import data from various data sources to TiDB |
| import_into.ui.swagger.json | UI-specific API documentation for the Data Import service, providing interfaces more suitable for frontend calls |
| premium_dm.swagger.json | Describes the API interfaces of the Premium Data Migration service, providing more advanced features |
| premium_dm.ui.swagger.json | UI-specific API documentation for the Premium Data Migration service |
| recovery-group-v1beta1.swagger.json | Describes the API interfaces of the Recovery Group service, used to manage data recovery groups |
| service.swagger.json | Describes the API interfaces of common services, including some shared API definitions |

## How to Use

### Viewing API Documentation

1. Use [Swagger UI](https://swagger.io/tools/swagger-ui/) to load these JSON files to view interactive API documentation.

2. You can also use other Swagger documentation tools like [ReDoc](https://github.com/Redocly/redoc) to view them.

### Generating Client Code

You can use tools like [Swagger Codegen](https://swagger.io/tools/swagger-codegen/) or [OpenAPI Generator](https://openapi-generator.tech/) to generate client code in various programming languages based on these Swagger files.

For example, using OpenAPI Generator to generate Go client code:

```bash
openapi-generator generate -i api/backup.swagger.json -g go -o ./backup-client
```

### Testing API Interfaces

You can use API testing tools like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/) to import these Swagger files and test API interfaces.

## How to Update

When service API interfaces change, you need to update the corresponding Swagger files. The update process is as follows:

1. Modify the API definitions in the corresponding service code
2. Regenerate the Swagger files
3. Submit the updated Swagger files to version control system

## Notes

- These Swagger files are automatically generated, do not edit them manually as this may cause inconsistencies with the actual API interfaces
- If you need to modify API interfaces, please modify the corresponding service code and then regenerate the Swagger files
- Ensure that Swagger files are consistent with actual API interfaces to avoid confusion for client developers