From 50c7b35291893e6e2fb695570a2983dcca1431c9 Mon Sep 17 00:00:00 2001
From: Mert <101130780+mertalev@users.noreply.github.com>
Date: Fri, 7 Jul 2023 21:49:18 -0400
Subject: [PATCH] clarified openapi use (#3149)

---
 docs/docs/developer/open-api.md     | 6 +++---
 docs/docs/developer/pr-checklist.md | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/docs/developer/open-api.md b/docs/docs/developer/open-api.md
index 0fdd5551f1..3989b45803 100644
--- a/docs/docs/developer/open-api.md
+++ b/docs/docs/developer/open-api.md
@@ -1,10 +1,10 @@
-# Open API
+# OpenAPI
 
-Immich uses the [Open API](https://swagger.io/specification/) standard to generate API documentation. To view the published docs see [here](/docs/api).
+Immich uses the [OpenAPI](https://swagger.io/specification/) standard to generate API documentation. To view the published docs see [here](/docs/api).
 
 ## Generator
 
-OpenAPI is used to generate the client (Typescript, Dart) SDK. `openapi-generator-cli` can be installed [here](https://openapi-generator.tech/docs/installation/). When you add a new or modify an existing endpoint, you must run the command below to update the client SDK.
+OpenAPI is used to generate the client (Typescript, Dart) SDK. `openapi-generator-cli` can be installed [here](https://openapi-generator.tech/docs/installation/). The generated SDK is based on the `immich-openapi-specs.json` file, which is autogenerated by the server when running in development mode. The `immich-openapi-specs.json` file can be modified with `@nestjs/swagger` decorators used or referenced by controller endpoints. See the [NestJS OpenAPI docs](https://docs.nestjs.com/openapi/types-and-parameters) for more info. When you add a new endpoint or modify an existing one, you must run the command below to update the client SDK.
 
 ```bash
 npm run api:generate # Run from the `server/` directory
diff --git a/docs/docs/developer/pr-checklist.md b/docs/docs/developer/pr-checklist.md
index efaa8f041f..4318f6106c 100644
--- a/docs/docs/developer/pr-checklist.md
+++ b/docs/docs/developer/pr-checklist.md
@@ -24,9 +24,9 @@ Run all web checks with `npm run check:all`
 Run all server checks with `npm run check:all`
 :::
 
-## Open API
+## OpenAPI
 
-The Open API client libraries need to be regenerated whenever there are changes to the `immich-openapi-specs.json` file. See [Open API](/docs/developer/open-api.md) for more details.
+The OpenAPI client libraries need to be regenerated whenever there are changes to the `immich-openapi-specs.json` file. Note that you should not modify this file directly as it is auto-generated. See [OpenAPI](/docs/developer/open-api.md) for more details.
 
 ## Database Migrations