Recreation Resource Services - RSTBC

• Contributing
• Code of Conduct
• License
• Security

Local Development

Prerequisites

• Node.js
• npm
• Docker OR PostgreSQL 15

Docker Compose

To run the entire application using Docker Compose, run the following commands:

git clone [email protected]:bcgov/nr-rec-resources.git
cd nr-rec-resources
docker-compose up

Navigate to http://localhost:3000 in your web browser to view the application.

Installation

Before starting development on this project, run npm install in the base directory to install eslint and plugins to ensure linting is working correctly.

Database

To run this on your local machine, you will need a working installation of PostgreSQL 16.

Create an .env file in the backend directory using the example in backend/.env.example as a template.

cd nr-rec-resources
make create_db
make migrate

Backend

Ensure you have the .env file in the backend directory from the previous step.

cd backend
npm install
npm run dev

OpenAPI/Swagger Documentation

The backend uses NestJS's built-in Swagger module (@nestjs/swagger) to automatically generate OpenAPI documentation from TypeScript decorators.

Swagger Decorators

Decorators are used throughout the codebase to provide metadata for API documentation:

• @ApiTags() - Groups related endpoints together
• @ApiOperation() - Describes what an endpoint does
• @ApiResponse() - Documents possible response types
• @ApiProperty() - Documents DTO properties and their types

Example usage in a controller:

@ApiTags("parks")
@Controller("parks")
export class ParksController {
  @Get()
  @ApiOperation({ summary: "Get all parks" })
  @ApiResponse({
    status: 200,
    description: "List of parks returned",
    type: [ParkDto],
  })
  findAll(): Promise<ParkDto[]> {
    return this.parksService.findAll();
  }
}

Accessing Generated Documentation

When running the backend server, Swagger UI is available at:

http://localhost:3000/api/docs

The raw OpenAPI specification can be accessed at:

http://localhost:3000/api/docs-json

This documentation is automatically generated from the TypeScript code and is used to:

• Provide interactive API documentation through Swagger UI
• Generate TypeScript client types using openapi-generator
• Ensure API consistency and type safety across the frontend and backend

Frontend

Create an .env file in the frontend directory using the example in frontend/.env.example as a template.

cd frontend
npm install
npm run dev

Navigate to http://localhost:3000 in your web browser to view the application.

Generate Client Library

Prerequisites

Install Java Development Kit (JDK) 17:

brew install openjdk@17

Generate TypeScript Axios Client

Run the following command to generate the TypeScript client library from your OpenAPI specification:

npx openapi-generator-cli generate -i http://localhost:3000/api/docs-json -g typescript-axios -o src/service/recreation-resource --skip-validate-spec

This command will:

• Generate TypeScript client code using Axios
• Use the OpenAPI spec from your local NestJS server which should be running on port 3000
• Output the generated code to src/service/recreation-resource directory

Pre-commit hooks

Pre-commit is set up to run checks for linting, formatting, and secrets.

• Install pre-commit
• With pre-commit installed run pre-commit install in the root directory of the project
• Pre-commit should now run on your staged files every time you make a commit

Skipping pre-commit hooks

If you need to skip the pre-commit hooks for a specific commit, you can use the --no-verify flag. Some developers may use this when they are making a commit that they know will fail the pre-commit checks, but they still want to commit the changes. This is a perfectly acceptible workflow, though there is a pre-commit check in CI so it may be necessary to run pre-commit on all files before putting a PR up for review if this is skipped.

git commit -m "Your commit message" --no-verify

Running pre-commit on all files

Sometimes it may be necessary to run pre-commit on the entire project due to a mistake or a configuration change.

pre-commit run --all-files

Style Guide

Commits follow the conventions defined in the Conventional Commits specification.

Schemaspy Database Schema Documentation

Schedule job runs every saturday and keep schema documentation upto date in github pages.