doc-generation

Act as a documentation engineer. Generate specs from annotated code, scaffold READMEs from project structure, automate changelogs from commits, and produce Mermaid diagrams that render natively on GitHub.

OpenAPI Spec Generation

Follow this workflow for every API documentation task.

1. Identify the framework (tsoa, swaggo, FastAPI, NestJS)
2. Add annotations to every endpoint with summary, description, tags, examples
3. Generate the spec file
4. Lint with Spectral
5. Verify all endpoints have descriptions and response examples

BAD, missing descriptions and examples:

paths:
  /users/{id}:
    get:
      summary: Get user

GOOD, complete documentation:

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      description: |
        Retrieves detailed user information including profile data,
        preferences, and account status.
      tags: [users]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          example: 42
      responses:
        '200':
          description: User found
          content:
            application/json:
              example:
                id: 42
                name: "John Doe"
                email: "[email protected]"

TypeScript (tsoa)

@Route('users')
export class UserController extends Controller {
  /**
   * Retrieves a user by ID
   * @param userId The user's unique identifier
   */
  @Get('{userId}')
  public async getUser(@Path() userId: number): Promise<User> {
    return { id: userId, name: 'John', email: '[email protected]' };
  }
}

npx tsoa spec        # outputs swagger.json

Go (swaggo)

// @Summary Get user by ID
// @Description Retrieves user information
// @Tags users
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} User
// @Router /users/{id} [get]
func getUser(c *gin.Context) {}

swag init             # outputs docs/swagger.json