docs: add better swagger description and release targets

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "api.opensauced.pizza",
+  "name": "@open-sauced/api.opensauced.pizza",
   "version": "1.12.0-beta.1",
   "keywords": [],
   "description": "API dot Open Sauced is NestJS and SupaBase powered OAS3 backend designed to remove client complexity and provide a structured graph of all @open-sauced integrations",

src/config/api.config.ts

@@ -4,7 +4,7 @@ export default registerAs("api", () => ({
   host: String(process.env.API_HOST ?? "0.0.0.0"),
   port: String(process.env.API_PORT ?? "3001"),
   domain: String(process.env.API_DOMAIN ?? "api.opensauced.pizza"),
-  development: (/watch/).test(String(process.env.npm_lifecycle_script ?? "node")),
+  development: String(process.env.npm_lifecycle_script ?? "node").includes("watch"),
   memory_heap: Number(parseInt(process.env.MEMORY_HEAP ?? "200", 10) * 1024 * 1024),
   memory_rss: Number(parseInt(process.env.MEMORY_RSS ?? "3000", 10) * 1024 * 1024),
   disk_percentage: Number(parseFloat(process.env.DISK_PERCENGATE ?? "0.7")),

src/main.ts

@@ -13,14 +13,58 @@ import { writeFile } from "node:fs/promises";
 import { major } from "semver";
 
 import { AppModule } from "./app.module";
-import { name, description, version, license } from "../package.json";
+import { name, version, license } from "../package.json";
 
 async function bootstrap () {
   const app = await NestFactory.create<NestFastifyApplication>(
     AppModule,
     new FastifyAdapter({ logger: false }),
   );
   const configService = app.get(ConfigService);
+  const apiDomain = String(configService.get("api.domain"));
+
+  const markdownDescription = `
+## Swagger-UI API Documentation
+
+This REST API can be used to create, read, update or delete data from the Open Sauced community platform.
+The Swagger-UI provides useful information to get started and an overview of all available resources.
+Each API route is clickable and has their own detailed description on how to use it.
+The base URL for the API is [${apiDomain}](https://${apiDomain}).
+
+[comment]: # (TODO: add bearer auth information)
+
+## Rate limiting
+
+Every IP address is allowed to perform 5000 requests per hour.
+This is measured by saving the date of the initial request and counting all requests in the next hour.
+When an IP address goes over the limit, HTTP status code 429 is returned.
+The returned HTTP headers of any API request show the current rate limit status:
+
+header | description
+--- | ---
+\`X-RateLimit-Limit\` | The maximum number of requests allowed per hour
+\`X-RateLimit-Remaining\` | The number of requests remaining in the current rate limit window
+\`X-RateLimit-Reset\` | The date and time at which the current rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time)
+
+[comment]: # (TODO: add pagination information)
+
+## Common response codes
+
+Each route shows for each method which data they expect and which they will respond when the call succeeds.
+The table below shows most common response codes you can receive from our endpoints.
+
+code | condition
+--- | ---
+[\`200\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) | The [\`GET\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) request was handled successfully. The response provides the requested data.
+[\`201\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201) | The [\`POST\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request was handled successfully. The response provides the created data.
+[\`204\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204) | The [\`PATCH\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) or [\`DELETE\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) request was handled successfully. The response provides no data, generally.
+[\`400\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400) | The server will not process the request due to something that is perceived to be a client error. Check the provided error for mote information.
+[\`401\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401) | The request requires user authentication. Check the provided error for more information.
+[\`403\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) | The request was valid, but the server is refusing user access. Check the provided error for more information.
+[\`404\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404) | The requested resource could not be found. Check the provided error for more information.
+[\`429\`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) | The current API Key made too many requests in the last hour. Check [Rate limiting](#ratelimiting) for more information.
+
+## Additional links`;
 
   app.enableCors();
   app.enableVersioning({
@@ -35,14 +79,14 @@ async function bootstrap () {
   }
 
   options
-    .addServer(`https://${<string>configService.get("api.domain")}`, "Production")
-    .addServer(`https://beta.${<string>configService.get("api.domain")}`, "Beta")
+    .addServer(`https://${apiDomain}`, "Production")
+    .addServer(`https://beta.${apiDomain}`, "Beta")
     .setTitle(name)
-    .setDescription(description)
+    .setDescription(markdownDescription)
     .setVersion(version)
-    .setContact("Open Sauced Triage Team", "https://opensauced.pizza", "hello@opensauced.pizza")
+    .setContact("Open Sauced", "https://opensauced.pizza", "hello@opensauced.pizza")
     .setTermsOfService("https://github.com/open-sauced/code-of-conduct")
-    .setLicense(license, `https://opensource.org/licenses/${license}`)
+    .setLicense(`The ${license} License`, `https://opensource.org/licenses/${license}`)
     .addBearerAuth();
 
   const document = SwaggerModule.createDocument(app, options.build(), {