Какие знаешь способы документирования API?

Способы документирования API

Документирование API — критически важный процесс в разработке. Хорошо задокументированный API снижает количество ошибок у клиентов, упрощает интеграцию и экономит время на поддержку.

1. OpenAPI / Swagger (Индустриальный стандарт)

Swagger — это YAML/JSON спецификация для описания REST API. OpenAPI — это эволюция Swagger (версия 3.x).

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: List of users

Java реализация — Springdoc OpenAPI:

@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "Users", description = "User management API")
public class UserController {
    
    @GetMapping
    @Operation(summary = "Get all users")
    public ResponseEntity<List<UserDto>> getAllUsers() {
        return ResponseEntity.ok(userService.getAll());
    }
}

2. GraphQL Schema (Для GraphQL API)

type User {
  id: ID!
  name: String!
  email: String!
  createdAt: DateTime!
}

type Query {
  user(id: ID!): User
  users(limit: Int = 20): [User!]!
}

3. AsyncAPI (Для асинхронных API)

Аналанична OpenAPI, но для очередей сообщений и Kafka/RabbitMQ топиков.

asyncapi: 2.6.0
info:
  title: Order Service
  version: 1.0.0
channels:
  order/created:
    description: When new order created

4. Javadoc + OpenAPI annotations

/**
 * Создание нового пользователя.
 * 
 * @param request DTO с данными
 * @return созданный пользователь с ID
 * @throws UserAlreadyExistsException если email занят
 */
@PostMapping
@Operation(summary = "Create user")
public ResponseEntity<UserDto> createUser(
    @RequestBody @Valid CreateUserRequest request
) {
    return ResponseEntity.status(201).body(userService.create(request));
}

5. REST Client (.http/.rest файлы)

Поддерживается в VS Code и IntelliJ IDEA:

### Get all users
GET http://localhost:8080/api/v1/users
Authorization: Bearer {{TOKEN}}

### Create user
POST http://localhost:8080/api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

6. Postman Collection

Экспортируется как JSON с примерами, тестами и переменными окружения.

{
  "info": {
    "name": "User API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Get all users",
      "request": {
        "method": "GET",
        "url": "{{base_url}}/api/v1/users"
      }
    }
  ]
}

7. Markdown Documentation

Просто, но эффективно для GitHub/GitLab:

# User API

## Authentication
Все endpoints требуют Bearer токен:
Authorization: Bearer {token}

## GET /api/v1/users
Получить список всех пользователей.

### Query Parameters
- page (int, default=0)
- size (int, default=20)

### Response (200)
```json
{
  "content": [{"id": 1, "name": "John"}],
  "totalElements": 100

}

### 8. **Spring REST Docs** (TDD подход)

Документация генерируется из тестов:

```java
@WebMvcTest(UserController.class)
public class UserControllerDocTest {
    
    @Autowired
    private MockMvc mockMvc;
    
    @Test
    public void documentGetAllUsers() throws Exception {
        mockMvc.perform(get("/api/v1/users"))
            .andExpect(status().isOk())
            .andDo(document("users/get-all",
                responseFields(
                    fieldWithPath("content[]").description("User array"),
                    fieldWithPath("content[].id").description("User ID")
                )
            ));
    }
}

9. PlantUML / Mermaid диаграммы

Для визуализации архитектуры и потоков:

sequenceDiagram
    participant Client
    participant API as User API
    participant DB as Database
    Client->>API: POST /users
    API->>DB: INSERT user
    DB-->>API: Success
    API-->>Client: 201 Created

10. Пример полной интеграции в Spring Boot

Добавь зависимость:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.0</version>
</dependency>

Создай конфигурацию:

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("User API")
                .version("1.0.0")
                .description("API управления пользователями")
            );
    }
}

Документируй контроллер:

@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "Users")
public class UserController {
    @GetMapping
    @Operation(summary = "Get all users")
    public List<UserDto> getAll() { }
    
    @PostMapping
    @Operation(summary = "Create user")
    @ApiResponse(responseCode = "201", description = "User created")
    public UserDto create(@RequestBody CreateUserRequest req) { }
}

Swagger UI доступен по http://localhost:8080/swagger-ui.html

Сравнение подходов

Выводы

1. OpenAPI/Swagger — лучший выбор для REST API с интерактивной документацией
2. GraphQL имеет встроенную документацию через интроспекцию
3. Spring REST Docs обеспечивает документацию из тестов (TDD)
4. Markdown хорош для простых проектов и README
5. Postman незаменим для примеров и тестирования
6. Всегда документируй: ошибки, статус-коды, примеры, требования
7. Автоматизируй генерацию из аннотаций, не вручную