Added OpenAPI documentation

.env.example

@@ -0,0 +1,4 @@
+GOOGLE_APPLICATION_CREDENTIALS=gcp-credentials.json
+BIGQUERY_PROJECT_ID=your-GCP-project-id
+GCS_BUCKET_NAME=your-GCS-bucket-name
+AUTH_API_ACCESS_KEY=create-one-from-TheAuthAPI.com

README.md

@@ -1,64 +1,79 @@
-## Description
+# Overture Maps API
 
-[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
+- Built using [NestJS](https://github.com/nestjs/nest) TypeScript Framework
 
 ## Endpoints
 
+- [OpenAPI Spec Doc](https://overture-maps-api.thatapicompany.com/api-docs.json)
 - [./Places](https://docs.overturemaps.org/guides/places/) - The Overture places theme has one feature type, called place, and contains more than 53 million point representations of real-world entities: schools, businesses, hospitals, religious organizations, landmarks, mountain peaks, and much more.
-- [./Places/Brands]
-- [./Places/Categories]
-- [./Places/Countries]
+- ./Places/Brands - Lists all the Brands used in the Places data, along with counts of Places for each.
+- ./Places/Categories - Lists all the Categories used in the Places data, along with counts of Places and Brands in each
+- ./Places/Countries - Lists all the Countries used in the Places data, along with counts of Places and Brands in each
 
 ### Schemas & Design
 
 - [API Design](./docs/api-design.md)
 - [Response Formats GeoJSON & JSON](./docs/response-formats.md)
 - [Place](https://docs.overturemaps.org/schema/reference/places/place/)
 - [Address](https://docs.overturemaps.org/schema/reference/addresses/address/)
+- [Overture Maps Official site](https://overturemaps.org/)
+- [Overture Maps API](https://docs.overturemaps.org/)
 
-### Extras
+### API Roadmap
 
-- [Overture Maps](https://overturemaps.org/)
-- [Overture Maps API](https://docs.overturemaps.org/)
+- [x] Places endpoint for Overture Maps 'Place' Theme
+- [x] Places/Brands endpoint
+- [x] Places/Categories endpoint
+- [x] Places/Countries endpoint
+- [ ] Places/Buildings endpoint
+- [ ] Addresses endpoint for Overture Maps 'Address' Theme
+- [ ] Base endpoint for Overture Maps 'Base' Theme
+- [ ] Buildings endpoint for Overture Maps 'Building' Theme
+- [ ] Transportation endpoint for Overture Maps 'Transportation' Theme
+- [ ] Divisions endpoint for Overture Maps 'Division' Theme
 
-### Data patching
+Extras:
 
-- Wikidata ID - is not always availble in the Overture Maps data. We can use the Wikidata API to get the wikidata_id for the place with a name and country match for best quess. This can be disabled in the request parameters via `patch_wikidata=false`.
+- [ ] Fill `wikidata` holes in the data
+- [ ] Add `wikidata` to the appropriate response for things like Brand logos, and more info
 
 ### Deployment & Datasets
 
 - [Google Cloud Platform](./docs/google-cloud-platform.md)
 
-
 ### API Key management
 
-You can either use the hardcoded API key in the code, or use the Auth API by going to theAuthAPI.com and creating an account. You can then create an Access Key for the App and add it as an Env var, and then create any number of API Keys for secure access to the API, and rate-limit them for cost control.
-
+You can either use the hardcoded API key in the code `DEMO-API-KEY`, or use the Auth API by going to theAuthAPI.com and creating an account. You can then create an Access Key for the App and add it as an Env var, and then create any number of API Keys for secure access to the API, and rate-limit them for cost control.
 
 ### Running Locally
 
-GCP: Download the Service Account .json file, and set the name in the .env variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of the file.
+- GCP: setup a key as per the [GCP guide](./docs/google-cloud-platform.md), then download the Service Account .json file locally, and set the name in the `.env` variable `GOOGLE_APPLICATION_CREDENTIALS` to the path of the file.
 
 ```bash
  npm install
+ npm run test
  npm run start
 ```
 
 Test the API by curl on `http://localhost:8080/places/countries` with the DEMO-API-KEY
 
 ```bash
-curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'http://localhost:8080/places/brands' -d 'country=AU'
+curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'http://localhost:8080/places/brands' \
+-d 'country=AU'
 ```
 
-```bash
-curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'http://localhost:8080/places/brands' -d 'country=AU' -d 'category=adult_store'
-```
+To get GeoJSON format, add `format=geojson` to the query string
 
 ```bash
-curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'http://localhost:8080/places' -d 'country=AU'  -d 'brand_name=TAB' -d 'limit=2' -d 'format=geojson'
+curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'http://localhost:8080/places' \
+-d 'country=AU'  -d 'brand_name=TAB' -d 'limit=2' -d 'format=geojson'
 ```
 
+To get the Categories or Brands filtered by Category for a Country
+
 ```bash
-curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'http://localhost:8080/places/categories' -d 'country=AU'
-curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'http://localhost:8080/places/brands' -d 'country=AU' -d 'categories=adult_store,airlines,airline'
-```
+curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'http://localhost:8080/places/categories' \
+-d 'country=AU'
+curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'http://localhost:8080/places/brands' \
+-d 'country=AU' -d 'categories=airlines,airline'
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "overture-maps-api",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "",
   "author": "",
   "private": true,
@@ -26,11 +26,13 @@
     "@nestjs/config": "^3.2.3",
     "@nestjs/core": "^10.0.0",
     "@nestjs/platform-express": "^10.0.0",
+    "@nestjs/swagger": "^8.0.1",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1",
     "dotenv": "^16.4.5",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.1",
+    "swagger-ui-express": "^5.0.1",
     "theauthapi": "^1.0.1-2.1"
   },
   "devDependencies": {

src/main.ts

@@ -3,6 +3,7 @@ import { ValidationPipe } from '@nestjs/common';
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
 import * as bodyParser from 'body-parser';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);  
@@ -26,6 +27,29 @@ async function bootstrap() {
   }
   app.enableCors(corsOptions);
   app.useGlobalPipes(new ValidationPipe({transform: true}));
+
+
+  // Configure Swagger
+  const config = new DocumentBuilder()
+    .setTitle('Overture Maps API Documentation')
+    .setDescription('Auto-generated OpenAPI spec for the Overture Maps API')
+    .setVersion('1.0')
+    .addServer('http://localhost:8080/', 'Local environment')
+    .addServer('https://overture-maps-api.thatapicompany.com','Cloud API Service')
+    .setContact("Aden Forshaw", "https://thatapicompany.com/overure-maps-api", "[email protected]")
+    .addApiKey(
+      { type: 'apiKey', name: 'x-api-key', in: 'header' },
+      'API_KEY', // Reference name for the security scheme
+    )
+    .addTag('places', 'Operations related to Places')
+    .build();
+
+  // Create the Swagger document
+  const document = SwaggerModule.createDocument(app, config);
+  // Serve the Swagger document at /api-docs
+  SwaggerModule.setup('api-docs', app, document,{jsonDocumentUrl: '/api-docs-json', swaggerUrl: '/api-docs-ui'});
+
+
   await app.listen(8080);
 }
 bootstrap();

src/middleware/auth-api.middleware.ts

@@ -47,7 +47,6 @@ export class AuthAPIMiddleware implements NestMiddleware {
 
     const apiKeyString = this.getAPIKeyFromHeaderOrQuery(req);
 
-    this.logger.log(`API Key: ${apiKeyString}`);
     //if no api key, or user is already set, skip
     if (!apiKeyString || req.res.locals['user']?.id ) {
       next();