0 Fork 0

Files

T

Alexander Abakumov 15e744da49 Initial commit: Complete Software Architecture course with 11 modules

- Added comprehensive course structure with 11 modules
- Included theoretical content, practical examples, and tasks
- Multi-language code examples (Java, Rust, Node.js, Python)
- Detailed analysis of architectural approaches and trade-offs
- Complete caching strategies documentation
- Architecture examples from real-world systems (Twitter, Netflix, Uber)
- Structured navigation and learning path
- Ready for educational use

2025-09-09 22:08:07 +03:00

4.9 KiB

Raw Permalink Blame History

Техническая документация

Документация API

1. OpenAPI Specification

openapi: 3.0.0
info:
  title: Order Service API
  version: 1.0.0
  description: API for managing orders

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

paths:
  /orders:
    post:
      summary: Create a new order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - customerId
        - items
      properties:
        customerId:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    
    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
        status:
          type: string
          enum: [CREATED, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
        totalAmount:
          type: number
          format: decimal
        createdAt:
          type: string
          format: date-time

2. API Documentation Tools

Swagger UI — интерактивная документация
ReDoc — альтернативный интерфейс
Postman — коллекции и тесты

Документация базы данных

1. Entity Relationship Diagrams

@startuml
title Order Database Schema

entity "users" {
    * id : UUID
    --
    * username : VARCHAR(50)
    * email : VARCHAR(100)
    * password_hash : VARCHAR(255)
    * created_at : TIMESTAMP
    * updated_at : TIMESTAMP
}

entity "orders" {
    * id : UUID
    --
    * user_id : UUID
    * status : VARCHAR(20)
    * total_amount : DECIMAL(10,2)
    * created_at : TIMESTAMP
    * updated_at : TIMESTAMP
}

entity "order_items" {
    * id : UUID
    --
    * order_id : UUID
    * product_id : UUID
    * quantity : INTEGER
    * unit_price : DECIMAL(10,2)
}

entity "products" {
    * id : UUID
    --
    * name : VARCHAR(100)
    * description : TEXT
    * price : DECIMAL(10,2)
    * stock_quantity : INTEGER
    * created_at : TIMESTAMP
    * updated_at : TIMESTAMP
}

users ||--o{ orders : "places"
orders ||--o{ order_items : "contains"
products ||--o{ order_items : "referenced in"

@enduml

2. Data Dictionary

# Data Dictionary

## Table: users

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PRIMARY KEY | Unique identifier for user |
| username | VARCHAR(50) | NOT NULL, UNIQUE | User's login name |
| email | VARCHAR(100) | NOT NULL, UNIQUE | User's email address |
| password_hash | VARCHAR(255) | NOT NULL | Hashed password |
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record creation timestamp |
| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record update timestamp |

## Table: orders

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PRIMARY KEY | Unique identifier for order |
| user_id | UUID | NOT NULL, FOREIGN KEY | Reference to users.id |
| status | VARCHAR(20) | NOT NULL | Order status (CREATED, CONFIRMED, etc.) |
| total_amount | DECIMAL(10,2) | NOT NULL | Total order amount |
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record creation timestamp |
| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record update timestamp |

Заключение

Техническая документация является основой для понимания и поддержки системы:

API документация — OpenAPI спецификации и интерактивные инструменты
Документация БД — ER диаграммы и словари данных
Структурированность — четкая организация и стандартизация
Актуальность — регулярное обновление и синхронизация с кодом

Правильная техническая документация значительно упрощает разработку, тестирование и поддержку системы.

4.9 KiB Raw Permalink Blame History