feat(api): REST API with OpenAPI for other apps, behind Pireon OAuth
A REST adapter next to GraphQL (presenters/http) that calls the same application services, so validation, permissions and domain errors are the same: projects (members, board, stats, activity), issues (search, workflow, assignee, release, links, comments, history), comments, releases and users. Projects and issues can be addressed by id or key (WEB, WEB-12). - Swagger UI at /api/docs, document at /api/docs-json and apps/api/openapi.json (rewritten by `nx serve api`, like schema.gql) for client generation. - Every route but health/auth/webhook needs a Pireon token: the document declares Pireon OAuth2 (authorization code + PKCE, password) through the /api/auth/token proxy, and a bearer scheme for apps with their own client. - configureApp() shares main.ts setup with the e2e, which now also covers REST. - SWAGGER_ENABLED / OPENAPI_FILE config; docs 03/05 and library READMEs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
215
libs/api/tracker/presenters/src/lib/http/dto/responses.dto.ts
Normal file
215
libs/api/tracker/presenters/src/lib/http/dto/responses.dto.ts
Normal file
@@ -0,0 +1,215 @@
|
||||
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
|
||||
import {
|
||||
IssueArea,
|
||||
IssueLinkType,
|
||||
IssuePriority,
|
||||
IssueStatus,
|
||||
IssueType,
|
||||
ProjectRole,
|
||||
ReleaseStatus,
|
||||
} from '@task-stream/api/tracker/domain';
|
||||
|
||||
/*
|
||||
* REST response bodies. Same shapes as the GraphQL types (both are views of
|
||||
* the read models); here they only document the contract for OpenAPI.
|
||||
*/
|
||||
|
||||
export class UserRefDto {
|
||||
@ApiProperty({ description: 'Pireon user id' }) id!: string;
|
||||
@ApiProperty() name!: string;
|
||||
}
|
||||
|
||||
export class ProjectMemberDto {
|
||||
@ApiProperty({ type: UserRefDto }) user!: UserRefDto;
|
||||
@ApiProperty({ enum: ProjectRole, enumName: 'ProjectRole' })
|
||||
role!: ProjectRole;
|
||||
}
|
||||
|
||||
export class ProjectDto {
|
||||
@ApiProperty({ format: 'uuid' }) id!: string;
|
||||
@ApiProperty({ example: 'WEB', description: 'Prefix of the ticket keys' })
|
||||
key!: string;
|
||||
@ApiProperty({ example: 'Checkout revamp' }) name!: string;
|
||||
@ApiProperty({ type: String, nullable: true }) description!: string | null;
|
||||
@ApiProperty({ type: UserRefDto }) owner!: UserRefDto;
|
||||
@ApiProperty({ type: [ProjectMemberDto] }) members!: ProjectMemberDto[];
|
||||
@ApiProperty({ format: 'date-time' }) createdAt!: string;
|
||||
@ApiProperty({ format: 'date-time' }) updatedAt!: string;
|
||||
@ApiProperty({ description: 'Version of the aggregate (event count)' })
|
||||
version!: number;
|
||||
}
|
||||
|
||||
export class IssueLinkDto {
|
||||
@ApiProperty({ enum: IssueLinkType, enumName: 'IssueLinkType' })
|
||||
type!: IssueLinkType;
|
||||
@ApiProperty({
|
||||
enum: ['OUTWARD', 'INWARD'],
|
||||
enumName: 'LinkDirection',
|
||||
description: 'OUTWARD: this issue → other. INWARD: other → this issue.',
|
||||
})
|
||||
direction!: 'OUTWARD' | 'INWARD';
|
||||
@ApiProperty({ format: 'uuid' }) issueId!: string;
|
||||
@ApiProperty({ example: 'WEB-3' }) issueKey!: string;
|
||||
}
|
||||
|
||||
export class ReleaseRefDto {
|
||||
@ApiProperty({ format: 'uuid' }) id!: string;
|
||||
@ApiProperty({ example: 'v1.4.0' }) name!: string;
|
||||
}
|
||||
|
||||
export class IssueDto {
|
||||
@ApiProperty({ format: 'uuid' }) id!: string;
|
||||
@ApiProperty({ format: 'uuid' }) projectId!: string;
|
||||
@ApiProperty({ example: 'WEB' }) projectKey!: string;
|
||||
@ApiProperty({ example: 12 }) number!: number;
|
||||
@ApiProperty({ example: 'WEB-12', description: 'Human key' }) key!: string;
|
||||
@ApiProperty({ enum: IssueType, enumName: 'IssueType' }) type!: IssueType;
|
||||
@ApiProperty({ enum: IssueArea, type: String, nullable: true })
|
||||
area!: IssueArea | null;
|
||||
@ApiProperty() title!: string;
|
||||
@ApiProperty({ type: String, nullable: true }) description!: string | null;
|
||||
@ApiProperty({ enum: IssueStatus, enumName: 'IssueStatus' })
|
||||
status!: IssueStatus;
|
||||
@ApiProperty({
|
||||
enum: IssueStatus,
|
||||
enumName: 'IssueStatus',
|
||||
isArray: true,
|
||||
description: 'Statuses this ticket can move to next',
|
||||
})
|
||||
allowedTransitions!: IssueStatus[];
|
||||
@ApiProperty({ enum: IssuePriority, enumName: 'IssuePriority' })
|
||||
priority!: IssuePriority;
|
||||
@ApiProperty({ type: UserRefDto }) reporter!: UserRefDto;
|
||||
@ApiProperty({ type: UserRefDto, nullable: true })
|
||||
assignee!: UserRefDto | null;
|
||||
@ApiProperty({ type: ReleaseRefDto, nullable: true })
|
||||
release!: ReleaseRefDto | null;
|
||||
@ApiProperty({ type: [String] }) labels!: string[];
|
||||
@ApiProperty({ type: String, nullable: true, description: 'Figma frame' })
|
||||
figmaUrl!: string | null;
|
||||
@ApiProperty({ type: Number, nullable: true }) storyPoints!: number | null;
|
||||
@ApiProperty({ type: String, nullable: true, format: 'date' })
|
||||
dueDate!: string | null;
|
||||
@ApiProperty({ type: [IssueLinkDto] }) links!: IssueLinkDto[];
|
||||
@ApiProperty() commentCount!: number;
|
||||
@ApiProperty({ format: 'date-time' }) createdAt!: string;
|
||||
@ApiProperty({ format: 'date-time' }) updatedAt!: string;
|
||||
@ApiProperty() version!: number;
|
||||
}
|
||||
|
||||
export class IssuePageDto {
|
||||
@ApiProperty({ type: [IssueDto] }) items!: IssueDto[];
|
||||
@ApiProperty({ description: 'Total matches (for pagination)' })
|
||||
total!: number;
|
||||
}
|
||||
|
||||
export class BoardColumnDto {
|
||||
@ApiProperty({ enum: IssueStatus, enumName: 'IssueStatus' })
|
||||
status!: IssueStatus;
|
||||
@ApiProperty({ type: [IssueDto] }) issues!: IssueDto[];
|
||||
@ApiProperty({ description: 'Tickets in the column (may exceed `issues`)' })
|
||||
total!: number;
|
||||
}
|
||||
|
||||
export class CommentDto {
|
||||
@ApiProperty({ format: 'uuid' }) id!: string;
|
||||
@ApiProperty({ format: 'uuid' }) issueId!: string;
|
||||
@ApiProperty({ type: UserRefDto }) author!: UserRefDto;
|
||||
@ApiProperty() body!: string;
|
||||
@ApiProperty({ format: 'date-time' }) createdAt!: string;
|
||||
@ApiProperty({ type: String, nullable: true, format: 'date-time' })
|
||||
editedAt!: string | null;
|
||||
@ApiProperty() version!: number;
|
||||
}
|
||||
|
||||
export class CommentPageDto {
|
||||
@ApiProperty({ type: [CommentDto] }) items!: CommentDto[];
|
||||
@ApiProperty() total!: number;
|
||||
}
|
||||
|
||||
export class ReleaseDto {
|
||||
@ApiProperty({ format: 'uuid' }) id!: string;
|
||||
@ApiProperty({ format: 'uuid' }) projectId!: string;
|
||||
@ApiProperty({ example: 'v1.4.0' }) name!: string;
|
||||
@ApiProperty({ type: String, nullable: true }) description!: string | null;
|
||||
@ApiProperty({ type: String, nullable: true, format: 'date' })
|
||||
targetDate!: string | null;
|
||||
@ApiProperty({ enum: ReleaseStatus, enumName: 'ReleaseStatus' })
|
||||
status!: ReleaseStatus;
|
||||
@ApiProperty({ type: String, nullable: true, format: 'date-time' })
|
||||
releasedAt!: string | null;
|
||||
@ApiProperty({ format: 'date-time' }) createdAt!: string;
|
||||
@ApiProperty() version!: number;
|
||||
}
|
||||
|
||||
export class CountByStatusDto {
|
||||
@ApiProperty({ enum: IssueStatus, enumName: 'IssueStatus' })
|
||||
key!: IssueStatus;
|
||||
@ApiProperty() count!: number;
|
||||
}
|
||||
|
||||
export class CountByKeyDto {
|
||||
@ApiProperty({ description: 'Type, priority or area ("NONE" = unset)' })
|
||||
key!: string;
|
||||
@ApiProperty() count!: number;
|
||||
}
|
||||
|
||||
export class CountByAssigneeDto {
|
||||
@ApiProperty({
|
||||
type: UserRefDto,
|
||||
nullable: true,
|
||||
description: 'Null = unassigned',
|
||||
})
|
||||
user!: UserRefDto | null;
|
||||
@ApiProperty() count!: number;
|
||||
}
|
||||
|
||||
export class ReleaseProgressDto {
|
||||
@ApiProperty() total!: number;
|
||||
@ApiProperty() finished!: number;
|
||||
@ApiProperty({ minimum: 0, maximum: 100 }) percent!: number;
|
||||
@ApiProperty({ type: [CountByStatusDto] }) byStatus!: CountByStatusDto[];
|
||||
}
|
||||
|
||||
export class ProjectStatsDto {
|
||||
@ApiProperty() total!: number;
|
||||
@ApiProperty({ description: 'Not done nor cancelled' }) open!: number;
|
||||
@ApiProperty({ type: [CountByStatusDto] }) byStatus!: CountByStatusDto[];
|
||||
@ApiProperty({ type: [CountByKeyDto] }) byType!: CountByKeyDto[];
|
||||
@ApiProperty({ type: [CountByKeyDto] }) byPriority!: CountByKeyDto[];
|
||||
@ApiProperty({ type: [CountByKeyDto] }) byArea!: CountByKeyDto[];
|
||||
@ApiProperty({
|
||||
type: [CountByAssigneeDto],
|
||||
description: 'Open tickets per person',
|
||||
})
|
||||
byAssignee!: CountByAssigneeDto[];
|
||||
}
|
||||
|
||||
export class ActivityDto {
|
||||
@ApiProperty() id!: string;
|
||||
@ApiProperty({ example: 'IssueStatusChanged' }) type!: string;
|
||||
@ApiProperty({ format: 'uuid' }) projectId!: string;
|
||||
@ApiProperty({ type: String, nullable: true }) issueId!: string | null;
|
||||
@ApiProperty({ type: String, nullable: true, example: 'WEB-12' })
|
||||
issueKey!: string | null;
|
||||
@ApiProperty({ type: UserRefDto }) actor!: UserRefDto;
|
||||
@ApiProperty({ example: 'Ana movió WEB-12 de En curso a En revisión' })
|
||||
summary!: string;
|
||||
@ApiProperty({ format: 'date-time' }) occurredAt!: string;
|
||||
}
|
||||
|
||||
export class CommandResultDto {
|
||||
@ApiProperty({ description: 'Id of the aggregate written' }) id!: string;
|
||||
@ApiPropertyOptional({
|
||||
description: 'Human key when one was assigned (project or issue)',
|
||||
example: 'WEB-13',
|
||||
})
|
||||
key?: string;
|
||||
@ApiProperty({
|
||||
description:
|
||||
'Version after the write. Writes are acknowledged at once and the read ' +
|
||||
'model catches up asynchronously: a GET may briefly return the previous ' +
|
||||
'version (or 404 right after a create).',
|
||||
})
|
||||
version!: number;
|
||||
}
|
||||
Reference in New Issue
Block a user