Merge pull request #35 from mnfst/openapi

doc: openapi

Author: brunobuddy

config.md

@@ -28,12 +28,12 @@ General environment variables.
 
 Environment variables related to paths.
 
-| Variable                 | Default                 | Description                                                                                                                 |
-| ------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| PUBLIC_FOLDER            | `/public`               | The public folder to show [static files](https://expressjs.com/en/starter/static-files.html)                                |
-| MANIFEST_HANDLERS_FOLDER | `/manifest/handlers`    | The folder to put your handlers functions for [custom endpoints](./endpoints.md)                                            |
-| MANIFEST_FILE_PATH       | `/manifest/backend.yml` | The relative or absolute path of your Manifest YAML file                                                                    |
-| TOKEN_SECRET_KEY         | `-`                     | The secret key behind the JWT authentication. Required on production, you can [generate one here](https://jwtsecrets.com/). |
+| Variable                 | Default         | Description                                                                                                                 |
+| ------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| PUBLIC_FOLDER            | `/public`       | The public folder to show [static files](https://expressjs.com/en/starter/static-files.html)                                |
+| MANIFEST_HANDLERS_FOLDER | `/handlers`     | The folder to put your handlers functions for [custom endpoints](./endpoints.md)                                            |
+| MANIFEST_FILE_PATH       | `/manifest.yml` | The relative or absolute path of your Manifest YAML file                                                                    |
+| TOKEN_SECRET_KEY         | `-`             | The secret key behind the JWT authentication. Required on production, you can [generate one here](https://jwtsecrets.com/). |
 
 ## Database
 
@@ -44,7 +44,7 @@ We recommend switching to [PostgreSQL](https://www.postgresql.org/) or [MySQL](h
 | Variable      | Default                | Description                                                               | Applies To         |
 | ------------- | ---------------------- | ------------------------------------------------------------------------- | ------------------ |
 | DB_CONNECTION | `sqlite`               | Choose `postgres` switching to PostgreSQL or `mysql` for MySQL or MariaDB | All                |
-| DB_PATH       | `/manifest/backend.db` | Path of the database. Your server should have access to this path locally | SQLite             |
+| DB_PATH       | `/.manifest/db.sqlite` | Path of the database. Your server should have access to this path locally | SQLite             |
 | DB_HOST       | `localhost`            | Database host                                                             | PostgreSQL / MySQL |
 | DB_PORT       | `5432`                 | Database port                                                             | PostgreSQL / MySQL |
 | DB_USERNAME   | `postgres`             | Database username                                                         | PostgreSQL / MySQL |
@@ -62,7 +62,7 @@ Here are examples of `.env` files for different database connections:
 
     DB_CONNECTION=sqlite
 
-    DB_PATH=/manifest/backend.db
+    DB_PATH=/.manifest/db.sqlite
 
     ```
 

crud.md

@@ -21,7 +21,9 @@ By default CRUD endpoints are private, only accessible for logged-in **admin** u
 
 ## Using the REST API
 
-Manifest exposes a REST API for CRUD operations. The **OpenAPI** documentation is automatically generated on http://localhost:1111/api. Have a look!
+Manifest exposes a REST API for CRUD operations. The **OpenAPI** documentation is automatically generated and the UI is available at http://localhost:1111/api. Have a look!
+
+An`openapi.yml` file is also generated along a `types.ts` file in the `./manifest` folder. Those 2 files are an amazing source of context for your **LLM**. If you want to connect a frontend to your Manifest backend, make sure that your **AI coding tool** sees those files to simplify your development.
 
 For CRUD endpoints, this prefix is followed by `collections` for [collections entities](#collections) and `singles` for [single entities](#singles) and by the slug of your entity (you can change it in the [entity params](entities.md#entity-params))
 

endpoints.md

@@ -21,23 +21,23 @@ Custom endpoints in Manifest follow a simple structure where you define:
 
 This is an example of a simple endpoint that returns a "Hello world from my new endpoint !" message when requesting `GET /endpoints/hello-world`.
 
-```yaml title="manifest/backend.yml"
+```yaml title="manifest.yml"
 endpoints:
   helloWorld:
     path: /hello-world
     method: GET
     handler: helloWorld
 ```
 
-```js title="manifest/handlers/helloWorld.js"
+```js title="handlers/helloWorld.js"
 module.exports = async (req, res) => {
   res.json({ message: 'Hello world from my new endpoint!' })
 }
 ```
 
 Manifest handlers are basically [ExpressJS middlewares](https://expressjs.com/en/guide/using-middleware.html) exposed with the [Manifest SDK](./crud.md#using-the-javascript-sdk) to help you work with your data.
 
-Place the handler file in the `/manifest/handlers` folder. For example, if the handler is `helloWorld`, the file should be `helloWorld.js`.
+Place the handler file in the `/handlers` folder. For example, if the handler is `helloWorld`, the file should be `helloWorld.js`.
 
 :::tip
 
@@ -61,9 +61,9 @@ Each endpoint can be defined in the YAML file with the following values:
 
 The next thing you may want to do is to **read and write data from your app**. This can be done using the Manifest backend SDK that shares the same CRUD and upload functions as the [JS SDK](http://localhost:3000/docs/javascript-sdk) for the front-end.
 
-Take the following example of a `backend.yml` file of a **leaderboard**:
+Take the following example of a `manifest.yml` file of a **leaderboard**:
 
-```yaml title="manifest/backend.yml"
+```yaml title="manifest.yml"
 name: Leaderboard app 🏅
 
 entities:
@@ -80,9 +80,9 @@ endpoints:
     handler: increaseScore
 ```
 
-We can now add the handler in the `/manifest/handlers` folder:
+We can now add the handler in the `/handlers` folder:
 
-```js title="manifest/handlers/increaseScore.js"
+```js title="/handlers/increaseScore.js"
 module.exports = async (req, res, manifest) => {
   // Get the requested competitor with the Manifest backend SDK.
   const competitor = await manifest

entities.md

@@ -12,15 +12,15 @@ import TabItem from '@theme/TabItem';
 
 An entity is a model of objects linked to real-world concepts. Creating an entity in manifest generates **CRUD endpoints** that can be used by the [REST API](./crud.md#using-the-rest-api) or the [SDK](./crud.md#using-the-javascript-sdk).
 
-All entities are located in the `backend.yml` file under the **entities** property.
+All entities are located in the `manifest.yml` file under the **entities** property.
 
 There are 2 types of entities in Manifest: [Collections](#collections) and [Singles](#singles). **Collections** are multiple instances of similar data, stored as a list. E.g., users, customers, videos, etc. Singles are unique, standalone data that are singular in nature. E.g., home content, about content, settings, logo...
 
 ## Collections
 
 Let's see a simple example:
 
-```yaml title="manifest/backend.yml"
+```yaml title="manifest.yml"
 name: A pet app
 
 entities:
@@ -133,9 +133,9 @@ Properties are the characteristics of your [entities](./entities.md). For exampl
 
 ### Syntax
 
-You can add the properties to your entities in the **backend.yml file**
+You can add the properties to your entities in the **manifest.yml file**
 
-```yaml title="manifest/backend.yml"
+```yaml title="manifest.yml"
 name: Blog about cats
 entities:
   Post 📝:
@@ -246,8 +246,8 @@ Timestamp field (ISO 8601 Format)
 ```
 
 #### Email
-You can create one-to-many relationships or many-to-many relationships. Defining relationships in your entities allows you to load relations when you query them and also filter by relations.
 
+You can create one-to-many relationships or many-to-many relationships. Defining relationships in your entities allows you to load relations when you query them and also filter by relations.
 
 ```yaml
 - { name: email, type: email }
@@ -349,7 +349,7 @@ You can create **one-to-many** relationships or **many-to-many** relationships.
 
 The following example showcases the possibilities of **Manifest relations**:
 
-```yaml title="manifest/backend.yml"
+```yaml title="manifest.yml"
 name: Basketball League 🏀
 
 entities:

middlewares.md

@@ -20,7 +20,7 @@ Here are some examples of middleware use cases:
 
 ## Syntax
 
-```yaml title="manifest/backend.yml"
+```yaml title="manifest.yml"
 entities:
   Project 🗂️:
     properties:
@@ -33,9 +33,9 @@ entities:
         - handler: sendEmail
 ```
 
-This example triggers the handler located at `/manifest/handlers/setDate.js` before the item is created and stored in the database, and triggers `/manifest/handlers/sendEmail.js` after.
+This example triggers the handler located at `/handlers/setDate.js` before the item is created and stored in the database, and triggers `/handlers/sendEmail.js` after.
 
-```js title="manifest/handlers/setDate.js"
+```js title="/handlers/setDate.js"
 module.exports = async (req, res) => {
   console.log('Hello from the handler!')
 
@@ -52,7 +52,7 @@ You can add **several middlewares** for an event. They will be processed sequent
 
 Manifest passes the [JS SDK](./crud.md#using-the-javascript-sdk) to handler functions as third argument. You can use it to fetch or write data.
 
-```js title="manifest/handlers/patchDocumentNameIfEmpty.js"
+```js title="/handlers/patchDocumentNameIfEmpty.js"
 module.exports = async (req, res, manifest) => {
   // If the 'name' property of the item is empty.
   if (!req.body['name']) {

validation.md

@@ -12,7 +12,7 @@ You can use the built-in **custom validators** to ensure that the data you are r
 
 ## Syntax
 
-In your **backend.yml**, you can add a _validation_ object that lists the properties and their validators:
+In your **manifest.yml**, you can add a _validation_ object that lists the properties and their validators:
 
 ```yaml
 entities:

webhooks.md

@@ -12,7 +12,7 @@ Webhooks are useful to connect other applications or to trigger a micro-service
 
 ## Syntax
 
-```yaml title="manifest/backend.yml"
+```yaml title="manifest.yml"
 entities:
   # You can attach one or several webhooks to each entity event.
   Cat 😺: