openapi: 3.0.0
info:
  title: Blog API
  description: REST API для блог-платформи
  version: 1.0.0
  contact:
    name: API Support
    email: support@blog.com

servers:
  - url: https://api.blog.com/v1
    description: Production server
  - url: http://localhost:3000/api
    description: Development server

tags:
  - name: Auth
    description: Автентифікація та авторизація
  - name: Posts
    description: Управління постами
  - name: Users
    description: Користувачі

paths:
  /auth/register:
    post:
      tags: [Auth]
      summary: Реєстрація нового користувача
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterDto'
      responses:
        '201':
          description: Користувач успішно зареєстрований
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Невалідні дані
        '409':
          description: Email вже зареєстрований

  /posts:
    get:
      tags: [Posts]
      summary: Отримати список постів
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Список постів
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'

components:
  schemas:
    RegisterDto:
      type: object
      required:
        - email
        - password
        - name
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        password:
          type: string
          minLength: 8
          example: SecurePass123!
        name:
          type: string
          example: John Doe

    UserResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time

    Post:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        content:
          type: string
        authorId:
          type: string
        published:
          type: boolean
        createdAt:
          type: string
          format: date-time

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

npm install --save @nestjs/swagger

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Глобальні налаштування
  app.setGlobalPrefix('api');
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,
    transform: true,
  }));

  // Конфігурація Swagger
  const config = new DocumentBuilder()
    .setTitle('Blog API')
    .setDescription('REST API для блог-платформи на NestJS')
    .setVersion('1.0')
    .addTag('auth', 'Автентифікація користувачів')
    .addTag('users', 'Управління користувачами')
    .addTag('posts', 'CRUD операції з постами')
    .addBearerAuth() // Додаємо підтримку JWT Bearer токенів
    .build();

  // Генерація OpenAPI документа
  const document = SwaggerModule.createDocument(app, config);

  // Налаштування Swagger UI за адресою /api/docs
  SwaggerModule.setup('api/docs', app, document, {
    swaggerOptions: {
      persistAuthorization: true, // Зберігає JWT токен між перезавантаженнями
    },
  });

  await app.listen(3000);
  console.log(`🚀 Server running on http://localhost:3000`);
  console.log(`📚 Swagger docs available at http://localhost:3000/api/docs`);
}

bootstrap();

// auth/auth.controller.ts
import { Controller, Post, Body } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';

@ApiTags('auth') // Група endpoints для автентифікації
@Controller('auth')
export class AuthController {
  @Post('register')
  register(@Body() dto: RegisterDto) {
    // ...
  }

  @Post('login')
  login(@Body() dto: LoginDto) {
    // ...
  }
}

import { ApiOperation } from '@nestjs/swagger';

@Post('register')
@ApiOperation({
  summary: 'Реєстрація нового користувача',
  description: 'Створює новий акаунт користувача. Email має бути унікальним. Пароль автоматично хешується через bcrypt.',
})
register(@Body() dto: RegisterDto) {
  return this.authService.register(dto);
}

import { ApiResponse } from '@nestjs/swagger';

@Post('register')
@ApiOperation({ summary: 'Реєстрація нового користувача' })
@ApiResponse({
  status: 201,
  description: 'Користувач успішно зареєстрований',
  type: UserResponseDto,
})
@ApiResponse({
  status: 400,
  description: 'Невалідні дані (email не відповідає формату, пароль занадто короткий)',
})
@ApiResponse({
  status: 409,
  description: 'Email вже зареєстрований у системі',
})
register(@Body() dto: RegisterDto): Promise<UserResponseDto> {
  return this.authService.register(dto);
}

import { ApiParam, ApiQuery, ApiBody } from '@nestjs/swagger';

@Get(':id')
@ApiParam({
  name: 'id',
  type: String,
  description: 'Унікальний ідентифікатор користувача (UUID)',
  example: '550e8400-e29b-41d4-a716-446655440000',
})
findOne(@Param('id') id: string) {
  return this.userService.findById(id);
}

@Get()
@ApiQuery({
  name: 'page',
  type: Number,
  required: false,
  description: 'Номер сторінки для пагінації',
  example: 1,
})
@ApiQuery({
  name: 'limit',
  type: Number,
  required: false,
  description: 'Кількість елементів на сторінці',
  example: 10,
})
findAll(@Query('page') page: number = 1, @Query('limit') limit: number = 10) {
  return this.userService.findAll(page, limit);
}

@Post()
@ApiBody({
  type: CreateUserDto,
  description: 'Дані для створення користувача',
  examples: {
    user1: {
      summary: 'Базовий користувач',
      value: {
        email: 'user@example.com',
        name: 'John Doe',
        password: 'SecurePass123!',
      },
    },
    admin: {
      summary: 'Адміністратор',
      value: {
        email: 'admin@example.com',
        name: 'Admin User',
        password: 'AdminPass123!',
        role: 'admin',
      },
    },
  },
})
create(@Body() dto: CreateUserDto) {
  return this.userService.create(dto);
}

// auth/dto/register.dto.ts
import { ApiProperty } from '@nestjs/swagger';
import { IsEmail, IsString, MinLength, MaxLength } from 'class-validator';

export class RegisterDto {
  @ApiProperty({
    description: 'Email-адреса користувача (має бути унікальною)',
    example: 'user@example.com',
    type: String,
    format: 'email',
  })
  @IsEmail()
  email: string;

  @ApiProperty({
    description: 'Пароль (мінімум 8 символів, має містити цифри та літери)',
    example: 'SecurePass123!',
    minLength: 8,
    maxLength: 128,
  })
  @IsString()
  @MinLength(8)
  @MaxLength(128)
  password: string;

  @ApiProperty({
    description: "Повне ім'я користувача",
    example: 'John Doe',
    minLength: 2,
    maxLength: 100,
  })
  @IsString()
  @MinLength(2)
  @MaxLength(100)
  name: string;
}

import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { IsOptional, IsBoolean } from 'class-validator';

export class UpdatePostDto {
  @ApiPropertyOptional({
    description: 'Новий заголовок поста',
    example: 'Updated Title',
  })
  @IsOptional()
  @IsString()
  title?: string;

  @ApiPropertyOptional({
    description: 'Оновлений контент поста',
    example: 'New content here...',
  })
  @IsOptional()
  @IsString()
  content?: string;

  @ApiPropertyOptional({
    description: 'Чи опублікований пост',
    example: true,
  })
  @IsOptional()
  @IsBoolean()
  published?: boolean;
}

export enum UserRole {
  USER = 'user',
  ADMIN = 'admin',
  MODERATOR = 'moderator',
}

export class CreateUserDto {
  @ApiProperty({
    description: 'Роль користувача у системі',
    enum: UserRole,
    default: UserRole.USER,
    example: UserRole.USER,
  })
  @IsEnum(UserRole)
  role: UserRole;
}

export class AddressDto {
  @ApiProperty({ example: 'Kyiv' })
  city: string;

  @ApiProperty({ example: 'Shevchenko St.' })
  street: string;

  @ApiProperty({ example: '01001' })
  postalCode: string;
}

export class CreateOrderDto {
  @ApiProperty({ description: 'Список ID товарів', type: [String] })
  productIds: string[];

  @ApiProperty({ description: 'Адреса доставки', type: AddressDto })
  shippingAddress: AddressDto;
}

// main.ts
const config = new DocumentBuilder()
  .setTitle('Blog API')
  .setVersion('1.0')
  .addBearerAuth() // Додає схему безпеки типу Bearer Token
  .build();

components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

import { ApiBearerAuth } from '@nestjs/swagger';

@Controller('posts')
@ApiTags('posts')
export class PostController {
  @Get()
  @ApiOperation({ summary: 'Отримати список постів (публічний)' })
  findAll() {
    return this.postService.findAll();
  }

  @Post()
  @ApiBearerAuth() // Вимагає Bearer токен
  @ApiOperation({ summary: 'Створити новий пост (requires auth)' })
  create(@Body() dto: CreatePostDto) {
    return this.postService.create(dto);
  }

  @Patch(':id')
  @ApiBearerAuth() // Вимагає Bearer токен
  @ApiOperation({ summary: 'Оновити пост (requires auth)' })
  update(@Param('id') id: string, @Body() dto: UpdatePostDto) {
    return this.postService.update(id, dto);
  }
}

npm install --save @scalar/nestjs-api-reference

// main.ts
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { apiReference } from '@scalar/nestjs-api-reference';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Генерація OpenAPI документа (як раніше)
  const config = new DocumentBuilder()
    .setTitle('Blog API')
    .setDescription('REST API для блог-платформи')
    .setVersion('1.0')
    .addBearerAuth()
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // Варіант 1: Лише Scalar (замість Swagger UI)
  app.use(
    '/api/docs',
    apiReference({
      spec: {
        content: document,
      },
      theme: 'purple', // 'default', 'moon', 'purple', 'solarized', 'bluePlanet'
      darkMode: true,
      layout: 'modern', // 'modern' або 'classic'
      showSidebar: true,
    }),
  );

  // Варіант 2: Обидва (Swagger UI + Scalar)
  SwaggerModule.setup('api/swagger', app, document); // Swagger UI
  app.use('/api/docs', apiReference({ spec: { content: document } })); // Scalar

  await app.listen(3000);
  console.log(`📚 Scalar docs: http://localhost:3000/api/docs`);
  console.log(`📚 Swagger UI: http://localhost:3000/api/swagger`);
}

bootstrap();

app.use(
  '/api/docs',
  apiReference({
    spec: {
      content: document,
    },
    // Тема та кольори
    theme: 'purple',
    darkMode: true,

    // Layout опції
    layout: 'modern',
    showSidebar: true,
    hideDarkModeToggle: false,
    hideDownloadButton: false,

    // Метадані
    metaData: {
      title: 'Blog API Documentation | Scalar',
      description: 'Interactive API documentation for Blog API',
      ogDescription: 'Explore and test Blog API endpoints',
      ogTitle: 'Blog API Docs',
      ogImage: 'https://example.com/og-image.png',
      twitterCard: 'summary_large_image',
    },

    // Custom CSS
    customCss: `
      .scalar-card {
        border-radius: 12px;
      }
      .scalar-button {
        font-weight: 600;
      }
    `,

    // Authentication налаштування
    authentication: {
      preferredSecurityScheme: 'bearer',
      apiKey: {
        token: process.env.DEFAULT_API_KEY, // Для dev
      },
    },

    // Серверні змінні
    servers: [
      {
        url: 'https://api.production.com',
        description: 'Production',
      },
      {
        url: 'http://localhost:3000',
        description: 'Development',
      },
    ],
  }),
);

arazzo: 1.0.0
info:
  title: Blog API Workflows
  version: 1.0.0
  description: Типові сценарії використання Blog API

sourceDescriptions:
  - name: blogAPI
    type: openapi
    url: /api/docs-json # Посилання на OpenAPI документ

workflows:
  - workflowId: user-registration-and-post-creation
    summary: Реєстрація користувача та створення поста
    description: Повний цикл від реєстрації до публікації першого поста
    
    inputs:
      type: object
      properties:
        userEmail:
          type: string
        userPassword:
          type: string
        userN ame:
          type: string
        postTitle:
          type: string
        postContent:
          type: string

    steps:
      - stepId: register
        description: Реєстрація нового користувача
        operationId: AuthController_register # Посилання на operationId з OpenAPI
        requestBody:
          contentType: application/json
          payload:
            email: $inputs.userEmail
            password: $inputs.userPassword
            name: $inputs.userName
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          userId: $response.body.id
          accessToken: $response.body.access_token

      - stepId: createPost
        description: Створення поста авторизованим користувачем
        operationId: PostController_create
        dependsOn: [register] # Цей крок залежить від успішного виконання register
        requestBody:
          contentType: application/json
          payload:
            title: $inputs.postTitle
            content: $inputs.postContent
            authorId: $steps.register.outputs.userId # Використання output попереднього кроку
        parameters:
          - name: Authorization
            in: header
            value: Bearer $steps.register.outputs.accessToken
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          postId: $response.body.id

      - stepId: publishPost
        description: Публікація створеного поста
        operationId: PostController_update
        dependsOn: [createPost]
        parameters:
          - name: id
            in: path
            value: $steps.createPost.outputs.postId
          - name: Authorization
            in: header
            value: Bearer $steps.register.outputs.accessToken
        requestBody:
          contentType: application/json
          payload:
            published: true
        successCriteria:
          - condition: $statusCode == 200
          - condition: $response.body.published == true

    outputs:
      userId: $steps.register.outputs.userId
      postId: $steps.createPost.outputs.postId
      postPublishedAt: $response.body.publishedAt

// Псевдокод для виконання Arazzo workflow
import { ArazzoRunner } from 'arazzo-runner';

const runner = new ArazzoRunner({
  arazzoSpec: 'workflows.arazzo.yaml',
  openApiSpec: 'openapi.json',
});

const result = await runner.executeWorkflow('user-registration-and-post-creation', {
  inputs: {
    userEmail: 'test@example.com',
    userPassword: 'SecurePass123!',
    userName: 'Test User',
    postTitle: 'My First Post',
    postContent: 'Hello, World!',
  },
});

console.log('Workflow completed:', result.success);
console.log('Outputs:', result.outputs);

npm install -g @openapitools/openapi-generator-cli

# Завантаження OpenAPI spec
curl http://localhost:3000/api/docs-json > openapi.json

# Генерація TypeScript Axios клієнта
openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-axios \
  -o ./src/generated/api \
  --additional-properties=npmName=blog-api-client,npmVersion=1.0.0

// Автоматично згенерований код
import { Configuration, AuthApi, PostsApi } from './generated/api';

const config = new Configuration({
  basePath: 'http://localhost:3000/api',
});

const authApi = new AuthApi(config);
const postsApi = new PostsApi(config);

// Реєстрація (типізовані параметри!)
const registerResponse = await authApi.authControllerRegister({
  email: 'user@example.com',
  password: 'SecurePass123!',
  name: 'John Doe',
});

const token = registerResponse.data.access_token;

// Створення поста (типізований response!)
const postResponse = await postsApi.postControllerCreate(
  {
    title: 'My Post',
    content: 'Content here',
  },
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  },
);

console.log('Post created:', postResponse.data.id);

openapi-generator-cli list