# Nean Api Docs

> Generate and serve OpenAPI documentation from NestJS decorators.

- **Type:** Skill
- **Install:** `agentstack add skill-edfenton-claude-skills-nean-api-docs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [edfenton](https://agentstack.voostack.com/s/edfenton)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [edfenton](https://github.com/edfenton)
- **Source:** https://github.com/edfenton/claude-skills/tree/main/nean/nean-api-docs

## Install

```sh
agentstack add skill-edfenton-claude-skills-nean-api-docs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Purpose
Generate and serve OpenAPI (Swagger) documentation using @nestjs/swagger decorators.

## Arguments
- `--serve` — Ensure Swagger UI is available at `/api/docs`
- `--export ` — Export OpenAPI spec to file (default: `openapi.json`)
- (no args) — Audit endpoints for missing documentation

## What gets created/updated

```
apps/api/src/
├── main.ts                     # Swagger setup (if not present)
└── modules/**/
    └── *.controller.ts         # API decorators added
    
openapi.json                    # Generated spec (if --export)
```

## How it works

NestJS Swagger reads decorators from:
1. **Controllers** — `@ApiTags`, `@ApiOperation`, `@ApiResponse`
2. **DTOs** — `@ApiProperty` from class-validator decorators
3. **Parameters** — `@ApiParam`, `@ApiQuery`, `@ApiBody`

## Decorator conventions

### Controller decorators
```typescript
@Controller('users')
@ApiTags('users')
@UseGuards(JwtAuthGuard)
@ApiBearerAuth()
export class UsersController {
  @Get()
  @ApiOperation({ summary: 'List all users' })
  @ApiPaginatedResponse(UserResponseDto)
  findAll(@Query() query: PaginationDto) {}

  @Get(':id')
  @ApiOperation({ summary: 'Get user by ID' })
  @ApiResponse({ status: 200, type: UserResponseDto })
  @ApiResponse({ status: 404, description: 'User not found' })
  findOne(@Param('id', ParseUUIDPipe) id: string) {}

  @Post()
  @ApiOperation({ summary: 'Create new user' })
  @ApiCreatedResponse({ type: UserResponseDto })
  @ApiBadRequestResponse({ description: 'Validation failed' })
  create(@Body() dto: CreateUserDto) {}
}
```

### DTO decorators
```typescript
export class CreateUserDto {
  @ApiProperty({ 
    description: 'User email address',
    example: 'user@example.com' 
  })
  @IsEmail()
  email: string;

  @ApiProperty({ 
    description: 'Display name',
    minLength: 1,
    maxLength: 100 
  })
  @IsString()
  @MinLength(1)
  @MaxLength(100)
  name: string;

  @ApiPropertyOptional({ 
    description: 'Profile bio',
    default: '' 
  })
  @IsOptional()
  @IsString()
  bio?: string;
}
```

## Swagger setup (main.ts)

```typescript
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

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

  // Swagger configuration
  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API documentation')
    .setVersion('1.0')
    .addBearerAuth()
    .addTag('health', 'Health check endpoints')
    .addTag('auth', 'Authentication endpoints')
    .addTag('users', 'User management')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api/docs', app, document, {
    swaggerOptions: {
      persistAuthorization: true,
    },
  });

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

## Swagger UI

When configured, Swagger UI is available at `/api/docs`:
- Interactive API explorer
- Try-it-out functionality (with auth)
- Schema visualization
- Download OpenAPI spec

## Audit checklist

When auditing documentation:
- [ ] All controllers have `@ApiTags`
- [ ] All endpoints have `@ApiOperation` with summary
- [ ] All response codes documented with `@ApiResponse`
- [ ] All DTOs have `@ApiProperty` decorators
- [ ] Examples provided for complex types
- [ ] Auth requirements documented (`@ApiBearerAuth`)
- [ ] Error responses documented

## Workflow
1. Ensure @nestjs/swagger is installed
2. Configure Swagger in main.ts
3. Audit controllers for missing decorators
4. Add decorators as needed
5. Verify documentation at /api/docs

## Output
- Endpoints documented count
- Missing documentation warnings
- Spec file location (if exported)

## Reference
For setup and customization, see `reference/nean-api-docs-reference.md`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [edfenton](https://github.com/edfenton)
- **Source:** [edfenton/claude-skills](https://github.com/edfenton/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-edfenton-claude-skills-nean-api-docs
- Seller: https://agentstack.voostack.com/s/edfenton
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.