Какой способ лучше всего использовать для разделения документации Swagger на два отдельных документа: один для клиентов и один для администраторов в Nest.js? 

У меня есть приложение на NestJS версии 11 и @nestjs/swagger версии 11.0.3. Я использую модульную архитектуру, где некоторые контроллеры разработаны для публичных клиентов (таких как мобильные и веб-приложения), а другие — для админ-панели. 

Когда я создаю документацию Swagger с помощью <code>SwaggerModule.createDocument()</code>, в финальную документацию попадают все контроллеры из модуля. Я хочу разделить документацию Swagger на два отдельных документа: 
- <i>/docs</i> для публичного API (клиенты) 
- <i>/docs-admin</i> для админского API 

Моя текущая конфигурация Swagger в файле main.ts выглядит следующим образом: 
<pre><code class="javascript">const config = new DocumentBuilder()
  .setTitle('API')
  .setDescription('API Documentation')
  .addServer(`${baseUrl}/${apiPrefix}`)
  .setVersion('1.0')
  .build();

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

SwaggerModule.setup('docs', app, document, {
  swaggerOptions: {
    search: true,
  },
});</code></pre> 

Кроме того, вот как выглядят файлы моего модуля: 

App.module.ts:
<pre><code class="javascript">@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    CacheModule.register({
      isGlobal: true,
    }),
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: createTypeOrmConfig,
    }),
    ApiModule,
  ],
})
export class AppModule {}</code></pre> 

api.module.ts:
<pre><code class="javascript">@Module({
  imports: [PerkProvidersModule, PerksModule],
})
export class MarketplaceDomainModule {}</code></pre> 

perks.module.ts:
<pre><code class="javascript">@Module({
  imports: [TypeOrmModule.forFeature([Perk]), PerkProvidersModule],
  providers: [PerksService],
  controllers: [Perks...</code></pre> 

Как мне настроить документацию Swagger так, чтобы она разделялась на два отдельных документа для публичного и админского API?
  • 27 апреля 2025 г. 15:45
Ответы на вопрос 1 
Для разделения документации Swagger на два отдельных документа в NestJS, вы можете создать два разных объекта документации, каждый из которых будет содержать только контроллеры, относящиеся к публичному API и админскому API соответственно. 

Вот шаги, которые вы можете выполнить для достижения этой цели:

1. **Разделите контроллеры на модули**: Убедитесь, что ваши контроллеры для публичного API и админского API разделены по модулям.

2. **Создайте документацию для каждого API**: В `main.ts` создайте два отдельных документа с использованием функции `createDocument`, указывая только те модули, которые необходимы для каждого документа.

Примерно так это может выглядеть для вашего случая:

```typescript
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

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

  // Создание конфигурации для публичного API
  const publicApiConfig = new DocumentBuilder()
    .setTitle('Public API')
    .setDescription('Documentation for public API')
    .setVersion('1.0')
    .build();

  const publicApiDocument = SwaggerModule.createDocument(app, publicApiConfig, {
    include: [ // Указываем модули для публичного API
      ApiModule, // Замените на свои модули для публичного API
    ],
  });

  SwaggerModule.setup('docs', app, publicApiDocument);

  // Создание конфигурации для админского API
  const adminApiConfig = new DocumentBuilder()
    .setTitle('Admin API')
    .setDescription('Documentation for admin API')
    .setVersion('1.0')
    .build();

  const adminApiDocument = SwaggerModule.createDocument(app, adminApiConfig, {
    include: [ // Указываем модули для админского API
      AdminModule, // Замените на свои модули для админского API
    ],
  });

  SwaggerModule.setup('docs-admin', app, adminApiDocument);

  await app.listen(3000);
}
bootstrap();
```

### Обратите внимание на следующие моменты:

- Используйте опцию `include` в `SwaggerModule.createDocument()`. Это позволяет указать, какие модули должны быть включены в документацию. Убедитесь, что вы указываете правильные модули для публичного и админского API.
- Проверьте, чтобы контроллеры, относящиеся к публичному и админскому API, были организованы в соответствующие модули, чтобы избежать путаницы.
- Настройте свои модули так, чтобы они соответствовали логике вашего приложения. Например, создайте модуль `AdminModule`, если его еще нет, и поместите туда все контроллеры, связанные с администрированием.

Теперь, когда вы запустите ваше приложение и перейдете по путям `/docs` и `/docs-admin`, вы увидите отдельные документы Swagger для публичного и админского API.
Похожие вопросы
    Показать ещё