feat(api-detail): isCurrent + setCurrent + màj doc et seeder
- Shared types : ajout isCurrent sur ApiEntry et ApiEntryListItem - Backend entity : colonne is_current (boolean, default true) - Backend service : isCurrent calculé à la création, setCurrent() marque une version comme courante (siblings → false) - Backend controller : POST /api/apis/:id/set-current - Frontend ApiService : méthode setCurrent() - Browse/upload : affichage badge "Courante" via isCurrent - Seeder : données de démo mises à jour - Documentation : api-reference, architecture, local-setup, CLAUDE.md Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
@@ -3,7 +3,7 @@
|
||||
## 1. Purpose & Architecture
|
||||
|
||||
**Datacat** est un catalogue de données d'API. Il permet d'importer des fichiers YAML
|
||||
(AsyncAPI ou OpenAPI) et de les transformer en documentation HTML via des CLI spécialisées.
|
||||
(AsyncAPI ou OpenAPI) et de les transformer en documentation HTML.
|
||||
|
||||
```
|
||||
datacat/
|
||||
@@ -19,8 +19,8 @@ datacat/
|
||||
User uploads YAML → POST /api/uploads
|
||||
→ ApiEntry created (status: PENDING)
|
||||
→ DocsGenerationService.generate()
|
||||
→ asyncapi generate fromFile input.yaml --output /docs-output/<id>/
|
||||
→ OR redocly build-docs input.yaml --output /docs-output/<id>/index.html
|
||||
→ AsyncAPI : API programmatique @asyncapi/generator (html-template local)
|
||||
→ OpenAPI : redocly build-docs input.yaml --output /docs-output/<id>/index.html
|
||||
→ ApiEntry updated (status: GENERATED, htmlPath: /docs-output/<id>/index.html)
|
||||
→ GET /api/apis/:id/docs → sendFile(htmlPath)
|
||||
```
|
||||
@@ -31,17 +31,15 @@ User uploads YAML → POST /api/uploads
|
||||
|
||||
```bash
|
||||
# Tout en Docker (recommandé)
|
||||
pnpm run dev # docker compose up
|
||||
pnpm run dev:build # docker compose up --build
|
||||
docker compose -f infra/docker-compose.yml up -d
|
||||
docker compose -f infra/docker-compose.yml up -d --build # avec rebuild
|
||||
|
||||
# Local (sans Docker)
|
||||
cd back && pnpm run start:dev # NestJS watch mode — port 3000
|
||||
cd back && pnpm run start:dev # NestJS watch mode — port 3000 interne / 3010 hôte
|
||||
cd front-public && pnpm run start # Angular dev server — port 4200
|
||||
|
||||
# Install deps
|
||||
cd back && pnpm install
|
||||
cd front-public && pnpm install
|
||||
cd shared && pnpm install
|
||||
# Install deps (depuis la racine workspace)
|
||||
pnpm install
|
||||
|
||||
# Build prod
|
||||
cd back && pnpm run build
|
||||
@@ -49,11 +47,21 @@ cd front-public && pnpm run build:prod
|
||||
```
|
||||
|
||||
### Proxy Angular → API
|
||||
Créer `front-public/proxy.conf.json` :
|
||||
`front-public/proxy.conf.json` (développement local) :
|
||||
```json
|
||||
{
|
||||
"/api": {
|
||||
"target": "http://localhost:3000",
|
||||
"target": "http://localhost:3010",
|
||||
"secure": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`front-public/proxy.conf.docker.json` (dans Docker) :
|
||||
```json
|
||||
{
|
||||
"/api": {
|
||||
"target": "http://backend:3000",
|
||||
"secure": false
|
||||
}
|
||||
}
|
||||
@@ -71,9 +79,10 @@ Créer `front-public/proxy.conf.json` :
|
||||
| TypeORM | ^0.3.20 |
|
||||
| PostgreSQL | 17 |
|
||||
| Angular | ^19.0.0 |
|
||||
| TypeScript | ^5.7.0 |
|
||||
| @asyncapi/cli | latest (in Docker) |
|
||||
| TypeScript | ~5.8.3 |
|
||||
| @asyncapi/cli | 6.0.0 (in Docker) |
|
||||
| @redocly/cli | latest (in Docker) |
|
||||
| @gouvfr/dsfr | ^1.13.0 (npm devDep front-public) |
|
||||
|
||||
### Conventions TypeScript
|
||||
- Pas de `any` — utiliser les types de `@datacat/shared`
|
||||
@@ -88,61 +97,110 @@ Créer `front-public/proxy.conf.json` :
|
||||
|
||||
```sql
|
||||
CREATE TABLE api_entries (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
title VARCHAR(255) NOT NULL,
|
||||
version VARCHAR(50) NOT NULL,
|
||||
description TEXT,
|
||||
type VARCHAR(10) NOT NULL CHECK (type IN ('ASYNCAPI', 'OPENAPI')),
|
||||
yaml_content TEXT NOT NULL,
|
||||
html_path VARCHAR(500),
|
||||
status VARCHAR(10) NOT NULL DEFAULT 'PENDING'
|
||||
CHECK (status IN ('PENDING', 'GENERATED', 'ERROR')),
|
||||
error_message TEXT,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
convention VARCHAR(30) NOT NULL DEFAULT 'CONSULTER'
|
||||
CHECK (convention IN ('CONSULTER','ENREGISTRER','ETRE_NOTIFIE')),
|
||||
name VARCHAR(255) NOT NULL DEFAULT '',
|
||||
provider VARCHAR(255) NOT NULL DEFAULT '',
|
||||
version_major INT NOT NULL DEFAULT 0,
|
||||
version_minor INT NOT NULL DEFAULT 0,
|
||||
version_patch INT NOT NULL DEFAULT 0,
|
||||
description TEXT,
|
||||
type VARCHAR(10) NOT NULL CHECK (type IN ('ASYNCAPI', 'OPENAPI')),
|
||||
yaml_content TEXT NOT NULL,
|
||||
html_path VARCHAR(500),
|
||||
status VARCHAR(10) NOT NULL DEFAULT 'PENDING'
|
||||
CHECK (status IN ('PENDING', 'GENERATED', 'ERROR')),
|
||||
error_message TEXT,
|
||||
category_id VARCHAR(36),
|
||||
contact_functional_name VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_functional_entity VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_functional_email VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_technical_name VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_technical_entity VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_technical_email VARCHAR(255) NOT NULL DEFAULT '',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
> `title` et `version` sont des champs **calculés** (pas en DB) :
|
||||
> - `title` = `CONVENTION_LABEL + ' ' + name` (ex: `"Consulter Petstore"`)
|
||||
> - `version` = `"major.minor.patch"` (ex: `"1.2.0"`)
|
||||
|
||||
### Entity TypeORM (`back/src/modules/apis/api-entry.entity.ts`)
|
||||
|
||||
```typescript
|
||||
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn } from 'typeorm';
|
||||
import { ApiType, ApiStatus } from '@datacat/shared';
|
||||
import { ApiType, ApiStatus, ApiConvention } from '@datacat/shared';
|
||||
|
||||
@Entity('api_entries')
|
||||
export class ApiEntryEntity {
|
||||
@PrimaryGeneratedColumn('uuid')
|
||||
id: string;
|
||||
id!: string;
|
||||
|
||||
@Column()
|
||||
title: string;
|
||||
@Column({ type: 'varchar', length: 30, default: 'CONSULTER' })
|
||||
convention!: ApiConvention;
|
||||
|
||||
@Column()
|
||||
version: string;
|
||||
@Column({ type: 'varchar', length: 255, default: '' })
|
||||
name!: string;
|
||||
|
||||
@Column({ nullable: true, type: 'text' })
|
||||
description: string | null;
|
||||
description!: string | null;
|
||||
|
||||
@Column({ type: 'varchar', length: 10 })
|
||||
type: ApiType;
|
||||
type!: ApiType;
|
||||
|
||||
@Column({ type: 'varchar', length: 255, default: '', name: 'provider' })
|
||||
provider!: string;
|
||||
|
||||
@Column({ type: 'int', default: 0, name: 'version_major' })
|
||||
versionMajor!: number;
|
||||
|
||||
@Column({ type: 'int', default: 0, name: 'version_minor' })
|
||||
versionMinor!: number;
|
||||
|
||||
@Column({ type: 'int', default: 0, name: 'version_patch' })
|
||||
versionPatch!: number;
|
||||
|
||||
@Column({ type: 'text', name: 'yaml_content' })
|
||||
yamlContent: string;
|
||||
yamlContent!: string;
|
||||
|
||||
@Column({ nullable: true, name: 'html_path' })
|
||||
htmlPath: string | null;
|
||||
@Column({ nullable: true, type: 'varchar', length: 500, name: 'html_path' })
|
||||
htmlPath!: string | null;
|
||||
|
||||
@Column({ type: 'varchar', length: 10, default: 'PENDING' })
|
||||
status: ApiStatus;
|
||||
status!: ApiStatus;
|
||||
|
||||
@Column({ nullable: true, type: 'text', name: 'error_message' })
|
||||
errorMessage: string | null;
|
||||
errorMessage!: string | null;
|
||||
|
||||
@Column({ nullable: true, type: 'varchar', length: 36, name: 'category_id' })
|
||||
categoryId!: string | null;
|
||||
|
||||
@Column({ type: 'varchar', length: 255, default: '', name: 'contact_functional_name' })
|
||||
contactFunctionalName!: string;
|
||||
|
||||
@Column({ type: 'varchar', length: 255, default: '', name: 'contact_functional_entity' })
|
||||
contactFunctionalEntity!: string;
|
||||
|
||||
@Column({ type: 'varchar', length: 255, default: '', name: 'contact_functional_email' })
|
||||
contactFunctionalEmail!: string;
|
||||
|
||||
@Column({ type: 'varchar', length: 255, default: '', name: 'contact_technical_name' })
|
||||
contactTechnicalName!: string;
|
||||
|
||||
@Column({ type: 'varchar', length: 255, default: '', name: 'contact_technical_entity' })
|
||||
contactTechnicalEntity!: string;
|
||||
|
||||
@Column({ type: 'varchar', length: 255, default: '', name: 'contact_technical_email' })
|
||||
contactTechnicalEmail!: string;
|
||||
|
||||
@CreateDateColumn({ name: 'created_at' })
|
||||
createdAt: Date;
|
||||
createdAt!: Date;
|
||||
|
||||
@UpdateDateColumn({ name: 'updated_at' })
|
||||
updatedAt: Date;
|
||||
updatedAt!: Date;
|
||||
}
|
||||
```
|
||||
|
||||
@@ -161,40 +219,60 @@ src/
|
||||
│ │ ├── apis.module.ts
|
||||
│ │ ├── apis.controller.ts # REST endpoints
|
||||
│ │ ├── apis.service.ts # CRUD logique
|
||||
│ │ └── api-entry.entity.ts # TypeORM entity
|
||||
│ │ ├── api-entry.entity.ts # TypeORM entity
|
||||
│ │ ├── api-entry.mapper.ts # entity → DTO (calcul title/version)
|
||||
│ │ └── dto/
|
||||
│ │ ├── create-api-entry.dto.ts
|
||||
│ │ └── update-api-entry.dto.ts
|
||||
│ ├── uploads/
|
||||
│ │ ├── uploads.module.ts
|
||||
│ │ └── uploads.controller.ts # POST /api/uploads (multipart)
|
||||
│ └── docs-generation/
|
||||
│ ├── docs-generation.module.ts
|
||||
│ └── docs-generation.service.ts # Appels AsyncAPI/Redocly CLI
|
||||
├── database/
|
||||
│ └── database.module.ts # TypeORM config (si séparé)
|
||||
│ │ └── uploads.controller.ts # POST /api/uploads + POST /api/uploads/validate
|
||||
│ ├── docs-generation/
|
||||
│ │ ├── docs-generation.module.ts
|
||||
│ │ └── docs-generation.service.ts # API programmatique @asyncapi/generator + redocly CLI
|
||||
│ ├── categories/
|
||||
│ │ ├── categories.module.ts
|
||||
│ │ ├── categories.controller.ts
|
||||
│ │ ├── categories.service.ts
|
||||
│ │ └── category.entity.ts
|
||||
│ └── seeder/
|
||||
│ ├── seeder.module.ts
|
||||
│ └── seeder.service.ts # Données de démo (idempotent, OnApplicationBootstrap)
|
||||
├── health/
|
||||
│ ├── health.module.ts
|
||||
│ └── health.controller.ts
|
||||
└── common/
|
||||
├── filters/
|
||||
│ └── all-exceptions.filter.ts
|
||||
└── interceptors/
|
||||
└── transform.interceptor.ts
|
||||
└── filters/
|
||||
└── all-exceptions.filter.ts
|
||||
```
|
||||
|
||||
### API REST
|
||||
|
||||
```
|
||||
GET /health → { status: 'ok' }
|
||||
GET /api/apis → ApiListResponse (+ ?search=&type=&page=&limit=)
|
||||
GET /api/apis/:id → ApiEntry
|
||||
POST /api/uploads → ApiEntry (multipart: file + title + version + description + type)
|
||||
PATCH /api/apis/:id → ApiEntry (body: UpdateApiEntryDto)
|
||||
DELETE /api/apis/:id → 204 No Content
|
||||
POST /api/apis/:id/regenerate → ApiEntry (relance la génération de docs)
|
||||
GET /api/apis/:id/docs → sendFile(htmlPath) ou 404 si pas encore généré
|
||||
GET /api/apis/:id/yaml → download du YAML brut (Content-Disposition: attachment)
|
||||
GET /health → { status: 'ok' }
|
||||
GET /api/apis → ApiListResponse (+ ?search=&type=&categoryId=&page=&limit=)
|
||||
GET /api/apis/:id → ApiEntry
|
||||
PATCH /api/apis/:id → ApiEntry (body: UpdateApiEntryDto)
|
||||
DELETE /api/apis/:id → 204 No Content
|
||||
POST /api/apis/:id/regenerate → ApiEntry (relance la génération de docs)
|
||||
GET /api/apis/:id/docs → sendFile(htmlPath) ou 404 si pas encore généré
|
||||
GET /api/apis/:id/*path → assets générés (CSS/JS référencés par index.html)
|
||||
GET /api/apis/:id/yaml → download du YAML brut (Content-Disposition: attachment)
|
||||
POST /api/uploads → ApiEntry (multipart: files 1..20 + métadonnées)
|
||||
POST /api/uploads/validate → résultat de validation (sans sauvegarde)
|
||||
GET /api/categories → liste flat toutes catégories
|
||||
GET /api/categories/browse → navigation racine (sous-catégories + APIs sans catégorie)
|
||||
GET /api/categories/browse/:id → navigation dans une catégorie
|
||||
GET /api/categories/:id → détail catégorie
|
||||
POST /api/categories → créer catégorie
|
||||
PATCH /api/categories/:id → modifier catégorie
|
||||
DELETE /api/categories/:id → supprimer (400 si non vide)
|
||||
```
|
||||
|
||||
### ApisController
|
||||
|
||||
```typescript
|
||||
import { Controller, Get, Patch, Delete, Post, Param, Body, Query, Res, NotFoundException } from '@nestjs/common';
|
||||
import { Controller, Get, Patch, Delete, Post, Param, Body, Query, Res, NotFoundException, HttpCode } from '@nestjs/common';
|
||||
import { Response } from 'express';
|
||||
|
||||
@Controller('apis')
|
||||
@@ -237,7 +315,7 @@ export class ApisController {
|
||||
@Get(':id/yaml')
|
||||
async getYaml(@Param('id') id: string, @Res() res: Response) {
|
||||
const entry = await this.apisService.findOneOrThrow(id);
|
||||
res.setHeader('Content-Disposition', `attachment; filename="${entry.title}.yaml"`);
|
||||
res.setHeader('Content-Disposition', `attachment; filename="${entry.name}.yaml"`);
|
||||
res.setHeader('Content-Type', 'application/x-yaml');
|
||||
res.send(entry.yamlContent);
|
||||
}
|
||||
@@ -247,8 +325,8 @@ export class ApisController {
|
||||
### UploadsController
|
||||
|
||||
```typescript
|
||||
import { Controller, Post, UseInterceptors, UploadedFile, Body } from '@nestjs/common';
|
||||
import { FileInterceptor } from '@nestjs/platform-express';
|
||||
import { Controller, Post, UseInterceptors, UploadedFiles, Body, BadRequestException } from '@nestjs/common';
|
||||
import { FilesInterceptor } from '@nestjs/platform-express';
|
||||
import { diskStorage } from 'multer';
|
||||
|
||||
@Controller('uploads')
|
||||
@@ -258,22 +336,38 @@ export class UploadsController {
|
||||
private readonly docsService: DocsGenerationService,
|
||||
) {}
|
||||
|
||||
// POST /api/uploads/validate — valide sans sauvegarder
|
||||
@Post('validate')
|
||||
@UseInterceptors(FilesInterceptor('files', 20, { /* diskStorage + fileFilter yaml */ }))
|
||||
async validate(@UploadedFiles() files: Express.Multer.File[]) {
|
||||
// Retourne { valid, type, mainFile, name, versionMajor, versionMinor, versionPatch, description, errors }
|
||||
}
|
||||
|
||||
// POST /api/uploads — crée l'entrée + lance la génération
|
||||
@Post()
|
||||
@UseInterceptors(FileInterceptor('file', {
|
||||
storage: diskStorage({ destination: '/tmp/uploads' }),
|
||||
fileFilter: (req, file, cb) => {
|
||||
if (!file.originalname.match(/\.(yaml|yml)$/)) {
|
||||
return cb(new Error('Only YAML files are allowed'), false);
|
||||
}
|
||||
cb(null, true);
|
||||
},
|
||||
}))
|
||||
@UseInterceptors(FilesInterceptor('files', 20, { /* diskStorage + fileFilter yaml */ }))
|
||||
async upload(
|
||||
@UploadedFile() file: Express.Multer.File,
|
||||
@Body() body: { title: string; version: string; description?: string; type: 'ASYNCAPI' | 'OPENAPI' },
|
||||
@UploadedFiles() files: Express.Multer.File[],
|
||||
@Body() body: {
|
||||
convention: string;
|
||||
name: string;
|
||||
provider: string;
|
||||
versionMajor: string; // string car multipart form-data
|
||||
versionMinor: string;
|
||||
versionPatch: string;
|
||||
description?: string;
|
||||
type?: 'ASYNCAPI' | 'OPENAPI'; // optionnel, détecté depuis le YAML
|
||||
categoryId?: string;
|
||||
contactFunctionalName: string;
|
||||
contactFunctionalEntity: string;
|
||||
contactFunctionalEmail: string;
|
||||
contactTechnicalName: string;
|
||||
contactTechnicalEntity: string;
|
||||
contactTechnicalEmail: string;
|
||||
},
|
||||
) {
|
||||
const yamlContent = fs.readFileSync(file.path, 'utf-8');
|
||||
const entry = await this.apisService.create({ ...body, yamlContent });
|
||||
// 1 fichier → lecture directe
|
||||
// N fichiers → détection fichier principal + bundling (redocly bundle / @asyncapi/bundler)
|
||||
// Fire and forget — génération asynchrone
|
||||
this.docsService.generate(entry.id).catch(console.error);
|
||||
return entry;
|
||||
@@ -289,19 +383,19 @@ import { execFile } from 'child_process';
|
||||
import { promisify } from 'util';
|
||||
import * as fs from 'fs/promises';
|
||||
import * as path from 'path';
|
||||
const AsyncApiGenerator = require('@asyncapi/generator');
|
||||
|
||||
const execFileAsync = promisify(execFile);
|
||||
|
||||
@Injectable()
|
||||
export class DocsGenerationService {
|
||||
private readonly outputDir = process.env.DOCS_OUTPUT_DIR ?? '/app/docs-output';
|
||||
private readonly outputDir = process.env.DOCS_OUTPUT_DIR ?? './docs-output';
|
||||
|
||||
async generate(entryId: string): Promise<void> {
|
||||
const entry = await this.apisService.findOneOrThrow(entryId);
|
||||
const entryDir = path.join(this.outputDir, entryId);
|
||||
|
||||
await fs.mkdir(entryDir, { recursive: true });
|
||||
|
||||
const yamlPath = path.join(entryDir, 'input.yaml');
|
||||
await fs.writeFile(yamlPath, entry.yamlContent, 'utf-8');
|
||||
|
||||
@@ -311,37 +405,32 @@ export class DocsGenerationService {
|
||||
} else {
|
||||
await this.generateOpenApi(yamlPath, entryDir);
|
||||
}
|
||||
|
||||
const htmlPath = path.join(entryDir, 'index.html');
|
||||
await this.apisService.update(entryId, { htmlPath, status: 'GENERATED' });
|
||||
await this.apisService.updateInternal(entryId, { htmlPath: path.join(entryDir, 'index.html'), status: 'GENERATED' });
|
||||
} catch (error) {
|
||||
await this.apisService.update(entryId, {
|
||||
status: 'ERROR',
|
||||
errorMessage: String(error),
|
||||
});
|
||||
await this.apisService.updateInternal(entryId, { status: 'ERROR', errorMessage: String(error) });
|
||||
}
|
||||
}
|
||||
|
||||
private async generateAsyncApi(yamlPath: string, outputDir: string): Promise<void> {
|
||||
// asyncapi generate fromFile <input> --output <dir>
|
||||
await execFileAsync('asyncapi', [
|
||||
'generate', 'fromFile',
|
||||
yamlPath,
|
||||
'--output', outputDir,
|
||||
]);
|
||||
// API programmatique — aucun appel réseau, template résolu localement
|
||||
const templatePath = path.join(process.cwd(), 'node_modules', '@asyncapi', 'html-template');
|
||||
const generator = new AsyncApiGenerator(templatePath, outputDir, { forceWrite: true });
|
||||
await generator.generateFromFile(yamlPath);
|
||||
}
|
||||
|
||||
private async generateOpenApi(yamlPath: string, outputDir: string): Promise<void> {
|
||||
// redocly build-docs <input> --output <file>
|
||||
await execFileAsync('redocly', [
|
||||
'build-docs',
|
||||
yamlPath,
|
||||
'build-docs', yamlPath,
|
||||
'--output', path.join(outputDir, 'index.html'),
|
||||
]);
|
||||
], { shell: true, env: execEnv });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Note** : `ApisService` expose deux méthodes de mise à jour :
|
||||
> - `update(id, dto: UpdateApiEntryDto)` — pour le controller (champs éditables par l'utilisateur)
|
||||
> - `updateInternal(id, fields)` — pour `DocsGenerationService` (status / htmlPath / errorMessage)
|
||||
|
||||
---
|
||||
|
||||
## 6. Conventions Angular 19
|
||||
@@ -362,44 +451,31 @@ import { ActivatedRoute } from '@angular/router';
|
||||
import { CommonModule } from '@angular/common';
|
||||
|
||||
@Component({
|
||||
selector: 'app-catalog',
|
||||
selector: 'app-browse',
|
||||
standalone: true,
|
||||
imports: [CommonModule],
|
||||
changeDetection: ChangeDetectionStrategy.OnPush,
|
||||
template: `
|
||||
<div class="fr-container fr-mt-4w">
|
||||
<h1 class="fr-h1">Catalogue des APIs</h1>
|
||||
<h1 class="fr-h1">Parcourir les APIs</h1>
|
||||
@if (loading()) {
|
||||
<div class="fr-callout">Chargement...</div>
|
||||
}
|
||||
@for (api of apis(); track api.id) {
|
||||
@for (cat of subcategories(); track cat.id) {
|
||||
<div class="fr-card fr-mb-2w">
|
||||
<h2>{{ api.title }}</h2>
|
||||
<h2>{{ cat.name }}</h2>
|
||||
</div>
|
||||
}
|
||||
</div>
|
||||
`,
|
||||
})
|
||||
export class CatalogComponent implements OnInit {
|
||||
export class BrowseComponent implements OnInit {
|
||||
private http = inject(HttpClient);
|
||||
|
||||
apis = signal<ApiEntryListItem[]>([]);
|
||||
subcategories = signal<CategoryWithCounts[]>([]);
|
||||
loading = signal(false);
|
||||
|
||||
ngOnInit() {
|
||||
this.loadApis();
|
||||
}
|
||||
|
||||
private loadApis() {
|
||||
this.loading.set(true);
|
||||
this.http.get<ApiListResponse>('/api/apis').subscribe({
|
||||
next: (res) => {
|
||||
this.apis.set(res.items);
|
||||
this.loading.set(false);
|
||||
},
|
||||
error: () => this.loading.set(false),
|
||||
});
|
||||
}
|
||||
ngOnInit() { /* ... */ }
|
||||
}
|
||||
```
|
||||
|
||||
@@ -438,23 +514,13 @@ export class ApiService {
|
||||
|
||||
## 7. DSFR (Système de Design de l'État)
|
||||
|
||||
### Installation (assets statiques — pas de package npm)
|
||||
### Installation via npm
|
||||
|
||||
Télécharger la dernière version depuis https://www.systeme-de-design.gouv.fr/
|
||||
et placer les assets dans `front-public/src/assets/dsfr/`.
|
||||
|
||||
Structure attendue :
|
||||
```bash
|
||||
# Déjà dans front-public/package.json :
|
||||
# "@gouvfr/dsfr": "^1.13.0" (devDependencies)
|
||||
# Assets copiés automatiquement via angular.json (assets config)
|
||||
```
|
||||
src/assets/dsfr/
|
||||
├── dsfr.min.css
|
||||
├── dsfr.module.min.js
|
||||
├── dsfr.nomodule.min.js
|
||||
└── utility/
|
||||
└── icons/
|
||||
└── icons.min.css
|
||||
```
|
||||
|
||||
Déjà référencé dans `index.html`.
|
||||
|
||||
### Classes CSS essentielles
|
||||
|
||||
@@ -506,24 +572,24 @@ fr-mt-4w fr-mb-2w fr-ml-1w fr-p-3w fr-mx-auto
|
||||
- `fr-icon-delete-bin-line` — supprimer
|
||||
- `fr-icon-refresh-line` — régénérer
|
||||
- `fr-icon-eye-line` — voir
|
||||
- `fr-icon-folder-2-line` — dossier
|
||||
- `fr-icon-edit-line` — éditer
|
||||
|
||||
---
|
||||
|
||||
## 8. Commandes AsyncAPI CLI & Redocly CLI
|
||||
## 8. Génération de documentation
|
||||
|
||||
### AsyncAPI CLI
|
||||
### AsyncAPI — API programmatique (pas CLI)
|
||||
|
||||
```bash
|
||||
# Générer HTML depuis un fichier YAML AsyncAPI
|
||||
asyncapi generate fromFile ./api.yaml --output ./output-dir/
|
||||
|
||||
# Valider un fichier
|
||||
asyncapi validate ./api.yaml
|
||||
|
||||
# Format de sortie : ./output-dir/index.html
|
||||
```typescript
|
||||
// Utilise @asyncapi/generator directement (installé dans node_modules)
|
||||
// Template @asyncapi/html-template pré-installé dans l'image Docker
|
||||
const templatePath = path.join(process.cwd(), 'node_modules', '@asyncapi', 'html-template');
|
||||
const generator = new AsyncApiGenerator(templatePath, outputDir, { forceWrite: true });
|
||||
await generator.generateFromFile(yamlPath);
|
||||
```
|
||||
|
||||
### Redocly CLI
|
||||
### OpenAPI — CLI Redocly
|
||||
|
||||
```bash
|
||||
# Générer HTML depuis un fichier OpenAPI YAML
|
||||
@@ -531,15 +597,17 @@ redocly build-docs ./api.yaml --output ./output-dir/index.html
|
||||
|
||||
# Valider un fichier OpenAPI
|
||||
redocly lint ./api.yaml
|
||||
|
||||
# Format de sortie : ./output-dir/index.html
|
||||
```
|
||||
|
||||
### Bundling multi-fichiers
|
||||
- **OpenAPI** : `redocly bundle <main> --output <bundled.yaml>`
|
||||
- **AsyncAPI** : API programmatique `@asyncapi/bundler`
|
||||
|
||||
### Notes importantes
|
||||
- Les deux CLIs sont installés dans l'image Docker prod (`infra/Dockerfile.prod`, target `back`)
|
||||
- En dev, ils sont installés dans `infra/Dockerfile.back.dev`
|
||||
- `@asyncapi/generator` et `@asyncapi/html-template` sont installés dans l'image Docker prod et dev
|
||||
- `@redocly/cli` est installé globalement dans les images Docker
|
||||
- La génération est **asynchrone** : l'upload crée l'entrée, puis la génération se fait en background
|
||||
- Le répertoire de sortie : `DOCS_OUTPUT_DIR=/app/docs-output` (PVC en prod)
|
||||
- Le répertoire de sortie : `DOCS_OUTPUT_DIR=/app/docs-output` (PVC en prod), `./docs-output` en dev
|
||||
- Chaque API a son propre sous-répertoire : `/app/docs-output/<uuid>/index.html`
|
||||
|
||||
---
|
||||
@@ -618,18 +686,6 @@ Dans `https://ci.chmod777.dev` → Settings → Secrets pour le dépôt `datacat
|
||||
- `registry_password` : token Gitea avec accès packages
|
||||
- `deploy_kubeconfig` : contenu du fichier `~/.kube/config`
|
||||
|
||||
### Dépôt Gitea
|
||||
Créer le dépôt `datacat` dans l'organisation `z3n` sur `https://git.chmod777.dev`.
|
||||
|
||||
```bash
|
||||
cd /home/flo/dev/datacat
|
||||
git init
|
||||
git remote add origin https://git.chmod777.dev/z3n/datacat.git
|
||||
git add .
|
||||
git commit -m "feat: initial scaffold"
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Règles de code
|
||||
@@ -637,7 +693,7 @@ git push -u origin main
|
||||
- **Langue** : code en anglais, commentaires en français
|
||||
- **Commits** : Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`)
|
||||
- **TypeScript** : pas de `any`, `strict: true`, types depuis `@datacat/shared`
|
||||
- **NestJS** : un module par feature (`ApisModule`, `UploadsModule`, `DocsGenerationModule`)
|
||||
- **NestJS** : un module par feature (`ApisModule`, `UploadsModule`, `DocsGenerationModule`, `CategoriesModule`)
|
||||
- **Angular** : standalone components, signals, inject(), OnPush, lazy loading
|
||||
- **Tests** : Vitest pour le backend, `ng test` pour le frontend
|
||||
- **Pas de `console.log`** en production — utiliser Pino (NestJS) ou le logger Angular
|
||||
@@ -646,30 +702,48 @@ git push -u origin main
|
||||
|
||||
## 12. Pages Angular — Détail d'implémentation
|
||||
|
||||
### `/browse` et `/browse/:id` — BrowseComponent
|
||||
- Navigation par dossiers DSFR (tuiles `fr-tile` ou cartes `fr-card`)
|
||||
- Fil d'Ariane DSFR (`fr-breadcrumb`) depuis le breadcrumb retourné par l'API
|
||||
- Boutons : créer dossier, éditer dossier (crayon), supprimer dossier
|
||||
- Modales partagées : `CategoryFormModalComponent` (créer/éditer), `CategoryDeleteModalComponent`
|
||||
- Recherche dans les APIs du dossier courant
|
||||
- `BrowseComponent` réutilisé pour `/browse` et `/browse/:id` — s'abonne à `paramMap` via `takeUntilDestroyed`
|
||||
|
||||
### `/catalog` — CatalogComponent
|
||||
- Grille DSFR de cartes (`fr-card`)
|
||||
- Champ de recherche (`fr-input`) filtrant titre + description
|
||||
- Champ de recherche (`fr-input`) filtrant `name`, `provider`, `description`, contacts
|
||||
- Select DSFR pour filtrer par type (ASYNCAPI / OPENAPI)
|
||||
- Pagination DSFR (`fr-pagination`)
|
||||
- Lien vers `/upload` avec bouton `fr-btn fr-btn--icon-left fr-icon-upload-2-line`
|
||||
|
||||
### `/catalog/:id` — ApiDetailComponent
|
||||
- Métadonnées : titre, version, description, type, statut (badge), dates
|
||||
- Fil d'Ariane aligné sur la hiérarchie des catégories
|
||||
- Titre affiché : `CONVENTION_LABEL + ' ' + name` (ex: `"Consulter Petstore"`)
|
||||
- Métadonnées : convention (badge), name, provider, version, description, type, statut, dates
|
||||
- Contacts métier (nom, entité, email) et technique (nom, entité, email)
|
||||
- Badge de statut : `fr-badge--success` (GENERATED), `fr-badge--warning` (PENDING), `fr-badge--error` (ERROR)
|
||||
- Boutons :
|
||||
- "Voir la documentation" → `/catalog/:id/docs` (désactivé si status ≠ GENERATED)
|
||||
- "Télécharger YAML" → `/api/apis/:id/yaml`
|
||||
- "Régénérer" → POST `/api/apis/:id/regenerate`
|
||||
- "Supprimer" → DELETE `/api/apis/:id` + redirect `/catalog`
|
||||
- "Modifier" → modale d'édition (tous les champs sauf yamlContent)
|
||||
- "Supprimer" → modale de confirmation → DELETE `/api/apis/:id` + redirect `/browse`
|
||||
|
||||
### `/catalog/:id/docs` — DocViewerComponent
|
||||
- `<iframe>` plein écran affichant `/api/apis/:id/docs`
|
||||
- Bouton "Retour" en haut
|
||||
|
||||
### `/upload` — UploadComponent
|
||||
- Stepper DSFR 3 étapes : (1) Choisir le fichier, (2) Métadonnées, (3) Confirmation
|
||||
- Étape 1 : Zone de drop DSFR (`fr-upload-group`) pour fichier `.yaml` / `.yml`
|
||||
- Étape 2 : Formulaire (titre, version, description, type select AsyncAPI/OpenAPI)
|
||||
- Stepper DSFR 3 étapes : (1) Choisir les fichiers, (2) Métadonnées, (3) Confirmation
|
||||
- Étape 1 : Zone de drop DSFR (`fr-upload-group`) pour 1 à 20 fichiers `.yaml` / `.yml`
|
||||
- Validation serveur via `POST /api/uploads/validate` dès la sélection
|
||||
- Pré-remplit les champs `name`, `versionMajor/Minor/Patch`, `description` depuis le YAML
|
||||
- Étape 2 : Formulaire — `convention` (select), `name`, `provider`, `versionMajor/Minor/Patch`,
|
||||
`description`, `categoryId` (optionnel), contacts métier + technique
|
||||
- Étape 3 : Récap + bouton "Importer"
|
||||
- POST multipart vers `/api/uploads`
|
||||
- Redirect vers `/catalog/:id` après succès
|
||||
|
||||
### Composants partagés
|
||||
- `CategoryFormModalComponent` — modale DSFR pour créer ou éditer une catégorie (nom, description, ordre)
|
||||
- `CategoryDeleteModalComponent` — modale DSFR de confirmation de suppression d'une catégorie
|
||||
|
||||
@@ -29,7 +29,7 @@ Liste les entrées avec filtres optionnels et pagination.
|
||||
|
||||
| Paramètre | Type | Défaut | Description |
|
||||
|-----------|------|--------|-------------|
|
||||
| `search` | string | — | Recherche dans le titre et la description (case-insensitive) |
|
||||
| `search` | string | — | Recherche dans `name`, `provider`, `description`, contacts (case-insensitive) |
|
||||
| `type` | `ASYNCAPI` \| `OPENAPI` | — | Filtre par type |
|
||||
| `categoryId` | UUID | — | Filtre par catégorie |
|
||||
| `page` | number | `1` | Page (min 1) |
|
||||
@@ -41,10 +41,13 @@ Liste les entrées avec filtres optionnels et pagination.
|
||||
"items": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "My API",
|
||||
"title": "Consulter Petstore",
|
||||
"name": "Petstore",
|
||||
"convention": "CONSULTER",
|
||||
"version": "1.0.0",
|
||||
"description": "...",
|
||||
"type": "OPENAPI",
|
||||
"provider": "Équipe Produit",
|
||||
"status": "GENERATED",
|
||||
"categoryId": "uuid-or-null",
|
||||
"createdAt": "2025-01-01T00:00:00.000Z",
|
||||
@@ -57,7 +60,7 @@ Liste les entrées avec filtres optionnels et pagination.
|
||||
}
|
||||
```
|
||||
|
||||
> `items` contient des `ApiEntryListItem` (sans `yamlContent` ni `htmlPath`).
|
||||
> `items` contient des `ApiEntryListItem` (sans `yamlContent`, `htmlPath`, contacts ni `versionMajor/Minor/Patch`).
|
||||
|
||||
---
|
||||
|
||||
@@ -69,15 +72,27 @@ Retourne le détail complet d'une entrée.
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "My API",
|
||||
"title": "Consulter Petstore",
|
||||
"name": "Petstore",
|
||||
"convention": "CONSULTER",
|
||||
"version": "1.0.0",
|
||||
"versionMajor": 1,
|
||||
"versionMinor": 0,
|
||||
"versionPatch": 0,
|
||||
"description": "...",
|
||||
"type": "OPENAPI",
|
||||
"provider": "Équipe Produit",
|
||||
"yamlContent": "openapi: '3.0.0'\n...",
|
||||
"htmlPath": "/app/docs-output/uuid/index.html",
|
||||
"status": "GENERATED",
|
||||
"errorMessage": null,
|
||||
"categoryId": "uuid-or-null",
|
||||
"contactFunctionalName": "Alice Martin",
|
||||
"contactFunctionalEntity": "DSI",
|
||||
"contactFunctionalEmail": "alice@example.com",
|
||||
"contactTechnicalName": "Bob Dupont",
|
||||
"contactTechnicalEntity": "Équipe Backend",
|
||||
"contactTechnicalEmail": "bob@example.com",
|
||||
"createdAt": "2025-01-01T00:00:00.000Z",
|
||||
"updatedAt": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
@@ -94,10 +109,20 @@ Met à jour les métadonnées d'une entrée (champs éditables par l'utilisateur
|
||||
**Body JSON** (tous les champs sont optionnels)
|
||||
```json
|
||||
{
|
||||
"title": "New title",
|
||||
"version": "2.0.0",
|
||||
"description": "Updated description",
|
||||
"categoryId": "uuid-or-null"
|
||||
"convention": "CONSULTER",
|
||||
"name": "Nouveau nom",
|
||||
"provider": "Équipe X",
|
||||
"versionMajor": 2,
|
||||
"versionMinor": 0,
|
||||
"versionPatch": 0,
|
||||
"description": "Description mise à jour",
|
||||
"categoryId": "uuid-or-null",
|
||||
"contactFunctionalName": "...",
|
||||
"contactFunctionalEntity": "...",
|
||||
"contactFunctionalEmail": "...",
|
||||
"contactTechnicalName": "...",
|
||||
"contactTechnicalEntity": "...",
|
||||
"contactTechnicalEmail": "..."
|
||||
}
|
||||
```
|
||||
|
||||
@@ -146,7 +171,7 @@ Télécharge le fichier YAML source.
|
||||
|
||||
**Réponse 200**
|
||||
- `Content-Type: application/x-yaml`
|
||||
- `Content-Disposition: attachment; filename="<title>.yaml"`
|
||||
- `Content-Disposition: attachment; filename="<name>.yaml"`
|
||||
- Corps : contenu YAML brut
|
||||
|
||||
**Réponse 404** — entrée introuvable
|
||||
@@ -155,6 +180,52 @@ Télécharge le fichier YAML source.
|
||||
|
||||
## Upload (`/api/uploads`)
|
||||
|
||||
### `POST /api/uploads/validate`
|
||||
|
||||
Valide 1 à 20 fichiers YAML sans créer d'entrée en base. Utilisé pour la validation en temps réel lors de l'upload.
|
||||
|
||||
**Content-Type** : `multipart/form-data`
|
||||
|
||||
**Champs du formulaire**
|
||||
|
||||
| Champ | Type | Requis | Description |
|
||||
|-------|------|--------|-------------|
|
||||
| `files` | file (1 à 20) | Oui | Fichiers YAML (`.yaml` ou `.yml`) |
|
||||
|
||||
**Réponse 200**
|
||||
```json
|
||||
{
|
||||
"valid": true,
|
||||
"type": "OPENAPI",
|
||||
"mainFile": "petstore.yaml",
|
||||
"name": "Petstore",
|
||||
"versionMajor": 1,
|
||||
"versionMinor": 0,
|
||||
"versionPatch": 0,
|
||||
"description": "A sample API",
|
||||
"errors": []
|
||||
}
|
||||
```
|
||||
|
||||
En cas d'erreur :
|
||||
```json
|
||||
{
|
||||
"valid": false,
|
||||
"type": null,
|
||||
"mainFile": null,
|
||||
"name": null,
|
||||
"versionMajor": null,
|
||||
"versionMinor": null,
|
||||
"versionPatch": null,
|
||||
"description": null,
|
||||
"errors": [
|
||||
{ "file": "api.yaml", "message": "erreur de syntaxe YAML — unexpected token" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/uploads`
|
||||
|
||||
Crée une nouvelle entrée à partir d'un ou plusieurs fichiers YAML.
|
||||
@@ -167,11 +238,21 @@ Lance la génération de documentation en arrière-plan (fire-and-forget).
|
||||
| Champ | Type | Requis | Description |
|
||||
|-------|------|--------|-------------|
|
||||
| `files` | file (1 à 20) | Oui | Fichiers YAML (`.yaml` ou `.yml`) |
|
||||
| `title` | string | Oui | Titre de l'API |
|
||||
| `version` | string | Oui | Version (ex: `1.0.0`) |
|
||||
| `convention` | `CONSULTER` \| `ENREGISTRER` \| `ETRE_NOTIFIE` | Oui | Convention d'échange |
|
||||
| `name` | string | Oui | Nom de l'API |
|
||||
| `provider` | string | Oui | Fournisseur / équipe responsable |
|
||||
| `versionMajor` | string (number) | Non | Version majeure (défaut: 0) |
|
||||
| `versionMinor` | string (number) | Non | Version mineure (défaut: 0) |
|
||||
| `versionPatch` | string (number) | Non | Version patch (défaut: 0) |
|
||||
| `description` | string | Non | Description libre |
|
||||
| `type` | `ASYNCAPI` \| `OPENAPI` | Non | Type (détecté automatiquement si absent) |
|
||||
| `categoryId` | UUID | Non | Catégorie parente |
|
||||
| `contactFunctionalName` | string | Non | Contact métier — nom |
|
||||
| `contactFunctionalEntity` | string | Non | Contact métier — entité |
|
||||
| `contactFunctionalEmail` | string | Non | Contact métier — email |
|
||||
| `contactTechnicalName` | string | Non | Contact technique — nom |
|
||||
| `contactTechnicalEntity` | string | Non | Contact technique — entité |
|
||||
| `contactTechnicalEmail` | string | Non | Contact technique — email |
|
||||
|
||||
**Détection automatique du type**
|
||||
|
||||
@@ -180,13 +261,13 @@ Le type est détecté à partir du contenu YAML :
|
||||
- Présence de `asyncapi:` en début de ligne → `ASYNCAPI`
|
||||
|
||||
Si plusieurs fichiers sont fournis, le fichier contenant la clé racine est considéré comme le fichier principal.
|
||||
Les autres sont bundlés via `redocly bundle` (OpenAPI) ou `asyncapi bundle` (AsyncAPI).
|
||||
Les autres sont bundlés via `redocly bundle` (OpenAPI) ou `@asyncapi/bundler` (AsyncAPI).
|
||||
|
||||
**Réponse 201** — `ApiEntry` créé avec `status: "PENDING"`
|
||||
|
||||
**Réponse 400**
|
||||
- Aucun fichier fourni
|
||||
- `title` ou `version` manquant
|
||||
- `name` ou `convention` manquant
|
||||
- Fichier non YAML
|
||||
- Type non détectable et non fourni
|
||||
- Aucun fichier principal trouvé dans un upload multi-fichiers
|
||||
@@ -243,8 +324,14 @@ Navigation à la racine : retourne les catégories de premier niveau et les APIs
|
||||
"apis": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "API sans catégorie",
|
||||
...
|
||||
"title": "Consulter API sans catégorie",
|
||||
"name": "API sans catégorie",
|
||||
"convention": "CONSULTER",
|
||||
"version": "1.0.0",
|
||||
"provider": "...",
|
||||
"status": "GENERATED",
|
||||
"categoryId": null,
|
||||
"..."
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -331,10 +418,11 @@ Met à jour une catégorie.
|
||||
### `DELETE /api/categories/:id`
|
||||
|
||||
Supprime une catégorie.
|
||||
Les APIs et sous-catégories enfants sont désassociées (`categoryId`/`parentId` mis à null).
|
||||
|
||||
**Réponse 204** — succès (pas de corps)
|
||||
|
||||
**Réponse 400** — le dossier contient des APIs ou des sous-dossiers (vérification applicative avant suppression)
|
||||
|
||||
**Réponse 404** — catégorie introuvable
|
||||
|
||||
---
|
||||
@@ -343,7 +431,7 @@ Les APIs et sous-catégories enfants sont désassociées (`categoryId`/`parentId
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 400 | Requête invalide (champ manquant, format incorrect) |
|
||||
| 400 | Requête invalide (champ manquant, format incorrect, suppression non vide) |
|
||||
| 404 | Ressource introuvable |
|
||||
| 500 | Erreur interne serveur |
|
||||
|
||||
@@ -365,3 +453,11 @@ Les APIs et sous-catégories enfants sont désassociées (`categoryId`/`parentId
|
||||
| `PENDING` | Entrée créée, génération de doc en cours |
|
||||
| `GENERATED` | Documentation HTML disponible |
|
||||
| `ERROR` | La génération a échoué (voir `errorMessage`) |
|
||||
|
||||
## Conventions d'échange
|
||||
|
||||
| Convention | Label affiché |
|
||||
|------------|---------------|
|
||||
| `CONSULTER` | Consulter |
|
||||
| `ENREGISTRER` | Enregistrer |
|
||||
| `ETRE_NOTIFIE` | Être notifié |
|
||||
|
||||
@@ -83,22 +83,37 @@ Injecte des données de démonstration au démarrage (idempotent : ne re-seed qu
|
||||
|
||||
```sql
|
||||
CREATE TABLE api_entries (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
title VARCHAR(255) NOT NULL,
|
||||
version VARCHAR(50) NOT NULL,
|
||||
description TEXT,
|
||||
type VARCHAR(10) NOT NULL CHECK (type IN ('ASYNCAPI', 'OPENAPI')),
|
||||
yaml_content TEXT NOT NULL,
|
||||
html_path VARCHAR(500),
|
||||
status VARCHAR(10) NOT NULL DEFAULT 'PENDING'
|
||||
CHECK (status IN ('PENDING', 'GENERATED', 'ERROR')),
|
||||
error_message TEXT,
|
||||
category_id VARCHAR(36),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
convention VARCHAR(30) NOT NULL DEFAULT 'CONSULTER'
|
||||
CHECK (convention IN ('CONSULTER','ENREGISTRER','ETRE_NOTIFIE')),
|
||||
name VARCHAR(255) NOT NULL DEFAULT '',
|
||||
provider VARCHAR(255) NOT NULL DEFAULT '',
|
||||
version_major INT NOT NULL DEFAULT 0,
|
||||
version_minor INT NOT NULL DEFAULT 0,
|
||||
version_patch INT NOT NULL DEFAULT 0,
|
||||
description TEXT,
|
||||
type VARCHAR(10) NOT NULL CHECK (type IN ('ASYNCAPI', 'OPENAPI')),
|
||||
yaml_content TEXT NOT NULL,
|
||||
html_path VARCHAR(500),
|
||||
status VARCHAR(10) NOT NULL DEFAULT 'PENDING'
|
||||
CHECK (status IN ('PENDING', 'GENERATED', 'ERROR')),
|
||||
error_message TEXT,
|
||||
category_id VARCHAR(36),
|
||||
contact_functional_name VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_functional_entity VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_functional_email VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_technical_name VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_technical_entity VARCHAR(255) NOT NULL DEFAULT '',
|
||||
contact_technical_email VARCHAR(255) NOT NULL DEFAULT '',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
> `title` et `version` sont des champs calculés (pas en DB) :
|
||||
> - `title` = `CONVENTION_LABEL + ' ' + name` (ex: `"Consulter Petstore"`)
|
||||
> - `version` = `"major.minor.patch"` (ex: `"1.0.0"`)
|
||||
|
||||
### Table `categories`
|
||||
|
||||
```sql
|
||||
@@ -114,7 +129,7 @@ CREATE TABLE categories (
|
||||
```
|
||||
|
||||
> Les relations `category_id` / `parent_id` sont des colonnes varchar sans contrainte de clé étrangère TypeORM.
|
||||
> La suppression d'une catégorie désassocie automatiquement ses APIs et sous-catégories enfants (logique applicative).
|
||||
> La suppression d'une catégorie est **rejetée avec 400** si le dossier contient des APIs ou des sous-dossiers (vérification applicative avant `DELETE`).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -138,6 +138,65 @@ Des exemples sont disponibles dans `documentation/` :
|
||||
|
||||
---
|
||||
|
||||
## Fixtures & re-seed
|
||||
|
||||
Les données de démo (catégories + APIs) sont définies dans `back/src/modules/seeder/seeder.service.ts`.
|
||||
|
||||
### Structure des fixtures
|
||||
|
||||
```
|
||||
E-commerce (racine)
|
||||
└─ Produits
|
||||
└─ Commandes
|
||||
└─ Notifications
|
||||
Infrastructure (racine)
|
||||
└─ Événements
|
||||
Identité & Accès (racine)
|
||||
└─ Authentification
|
||||
```
|
||||
|
||||
5 APIs de démo y sont rattachées (Petstore, Streetlights Kafka, Account Service, Orders, Auth JWT).
|
||||
|
||||
### Modifier les fixtures
|
||||
|
||||
Éditer directement `back/src/modules/seeder/seeder.service.ts` :
|
||||
|
||||
- **Catégories** : bloc `categoryRepo.save(categoryRepo.create({...}))` dans la méthode `seed()`. Utiliser `parentId: null` pour une racine, ou `parentId: autreCategorie.id` pour un enfant.
|
||||
- **APIs** : tableau passé à `apiRepo.save([...])`. Chaque entrée référence une catégorie via `categoryId`.
|
||||
- **YAML** : les constantes en haut du fichier (`PETSTORE_YAML`, `ORDERS_YAML`, etc.) contiennent le YAML inliné de chaque API.
|
||||
|
||||
### Régénérer la base de données
|
||||
|
||||
Le seeder est **idempotent** : il ne s'exécute pas si la table `api_entries` contient déjà des lignes.
|
||||
|
||||
Pour forcer un re-seed complet (vide tout et recrée), utiliser la variable `FORCE_RESEED=true` :
|
||||
|
||||
**Avec Docker :**
|
||||
```bash
|
||||
docker compose -f infra/docker-compose.yml stop backend
|
||||
docker compose -f infra/docker-compose.yml run --rm -e FORCE_RESEED=true backend
|
||||
```
|
||||
|
||||
**Sans Docker (local) :**
|
||||
```bash
|
||||
cd back
|
||||
FORCE_RESEED=true pnpm run start:dev
|
||||
```
|
||||
|
||||
Ou via `back/.env` :
|
||||
```env
|
||||
FORCE_RESEED=true
|
||||
```
|
||||
> Penser à retirer `FORCE_RESEED=true` du `.env` après le redémarrage, sinon la base sera réinitialisée à chaque démarrage.
|
||||
|
||||
Le seeder supprime toutes les entrées `api_entries` et `categories`, nettoie le répertoire `docs-output`, puis recrée tout depuis `seed()`. Les logs confirment l'opération :
|
||||
```
|
||||
[Seeder] Reset complet — données supprimées, docs nettoyées.
|
||||
[Seeder] 8 catégories et 5 APIs de démo créées — génération docs en cours...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Schéma DB** : TypeORM crée et synchronise automatiquement les tables au démarrage (mode `synchronize: true` hors production). Aucune migration manuelle nécessaire.
|
||||
|
||||
Reference in New Issue
Block a user