Dynamically generate openapi site

Change the strategy for managing the open api static site.
Instead of committing at each change, remove from source control and
generate when running the API.

closes #273

.gitignore

@@ -1,6 +1,7 @@
 # compiled output
 /dist
 /node_modules
+/openapi/index.html
 
 # temporary directory
 /temp

README.md

@@ -1,22 +1,25 @@
 # Zoning API
-This project is an API for serving data related to zoning, such as zoning districts and tax lots.
+This project includes an API to interact with data from city planning and OpenAPI documentation for the available endpoints. 
 
-## Running the project locally
+## Local API Setup
 
-### Make sure you're using the correct version of Node
-The `.nvmrc` file tells you which version of node you should be using to run the project. If you're using [nvm](https://github.com/nvm-sh/nvm) and already have the correct version installed, you can switch by running `nvm use` from the root of this repo.
+### Use the correct version of Node
+The `.nvmrc` file tells you which version of node you should be using to run the project. 
+If you're using [nvm](https://github.com/nvm-sh/nvm) and already have the correct version installed, 
+you can switch by running `nvm use` from the root of this repo.
 
 ### Install dependencies
 Once you have cloned this repo, install the necessary dependencies:
-```
+```sh
 npm i
 ```
+
 ### Set up your `.env` file
 Create a file called `.env` in the root folder of the project and copy the contents of `sample.env` into that new file
 
 ### Run local database with docker compose
-Next, use [docker compose](https://docs.docker.com/compose/) to stand up a local Postgresql database. 
-```
+Next, use [docker compose](https://docs.docker.com/compose/) to stand up a local Postgres database. 
+```sh
 docker compose up
 ```
 
@@ -25,42 +28,82 @@ If you need to install docker compose, follow [these instructions](https://docs.
 ### Configure PostGIS
 Enable geospatial features by installing the postgis extension
 
-```
+```sh
 npm run pg:configure
 ```
 
 ### Drizzle ORM setup
 Structure the database tables with drizzle
 
-```
+```sh
 npm run drizzle:migrate
 ```
 
 ### Data loading
 Load the data into the tables. Under the hood, this uses the Postgres COPY command.
 
-```
+```sh
 npm run pg:copy
 ```
 
-### Run the project
-Finally, to run the project locally:
+## Local development
+The OpenAPI documentation and the API implementation complement each other. 
+The OpenAPI documentation is written first, defining expectations for endpoints.
+The API is subsequently implemented based on the OpenAPI documentation.
+
+### OpenAPI development
+The OpenAPI documentation is written in the `openapi/openapi.yaml` file.
+The [redoc](https://redocly.com/docs/redoc/) cli provides commands to manage the documentation,
+with a few key commands integrated into npm scripts.
+
+When writing OpenAPI documentation:
+- run `npm run redoc:dev`
+- open localhost:8080
+- make edits to `openapi/openapi.yaml`
+- view the updates in real time through port 8080
+
+To check validity of OpenAPI documentation:
+- run `npm run redoc:lint`
+
+### API development
+The API integrates with the OpenAPI documentation by implementing its endpoints. 
+The OpenAPI documentation defines schemas for the API to interact with. 
+
+The API uses [Kubb](https://www.kubb.dev) to automatically generate 
+Typescript definitions and zod schemas from the OpenAPI documentation.
+The generated code is kept in `/src/gen`. Never make manual changes to files in this folder.
+
+Generate these resources with:
+```sh
+npm run generate
 ```
-npm run dev
+
+The console may include the output below. It can be safely ignored.
+```console
+✖ Something went wrong
+
+  Error: The "paths[0]" argument must be of type string. Received undefined
 ```
-### OpenApi documentation
-Open Api documentation is managed through [redoc](https://redocly.com/docs/redoc/). Changes to the documentation are managed through edits to the `openapi/openapi.yaml` file. The `openapi/index.html` is used to serve the rendered documentation. It is generated through the redocly cli and should not be manually edited.
 
-The api serves the documentation on its root path.
+Finally, to run the api locally:
+```sh
+npm run dev
+```
 
-- To serve a development version of the rendered documentation while making edits, use `npm run redoc:dev`.
-- To check for linting errors in the `openapi/openapi.yaml`, use `npm run redoc:lint`.
-- To rebuild the `openapi/index.html` with the latest changes to the `openapi/openapi.yaml`, use `npm run redoc:build`
-  - The api serves the documentation from this html file. It is only updated when it is specifically rebuilt.
+(This command will also create a static site of the OpenAPI documentation at the root of the API.
+This site reflects the documentation at the point where the command was written. Viewing changes to
+the OpenAPI documentation requires restarting the development server).
 
-For production workflows, `npm run build` includes the command to build the documentation into the html file, ensuring the production site serves the latest api documentation.
+## Production builds
+Running a production version of the site is a two step process.
+First, generate production versions of the OpenAPI documentation and API.
+Both of these steps are combined into the same script:
+```sh
+npm run build
+```
 
-### OpenApi code generation
-This project makes use of [Kubb](https://www.kubb.dev) to generate code based on the `openapi.yaml` file. Kubb is configured in the `kubb.config.ts` file to use the `@kubb/swagger-ts` and `@kubb/swagger-zod` plugins to generate typescript types and Zod schemas. These types and schemas can then be used to perform validation on route params, query params, and request bodies via the `ZodValidationPipe` custom Nest pipe.
+Then, run the production build:
+```sh
+npm run start:prod
+```
 
-This code is kept in `/src/gen`. Developers working on this project should never make manual changes to the contents of that folder. To update the generated code to reflect changes to `openapi.yaml`, run `npm run generate`.