@chillapi/generator-tools
This package is used by any plugin that wants to generate a ChillAPI configuration.
Goals
Generate ChillAPI Config folder structure and operation descriptors
Available options:
-
rootDirectory:string
: the location where the ChillAPI configuration should be saved; default./chillapi
-
descriptorContent:function(op:OpenAPIOperation)=>string
: a function that takes an OpenAPI operation and returns the content to be filled into the respective ChillAPI descriptor
The ChillAPI folder structure shall be created in the chose root directory, as follows:
- OpenAPI paths translated into directories, normalizing for compatibility
- One empty ChillAPI descriptor file for each method
Example:
paths:
/article:
get:
summary: Get all articles
operationId: getArticles
...
post:
tags:
- article
summary: Add an article
operationId: addArticle
...
'/article/{id}':
put:
tags:
- article
summary: Modify an article
operationId: updateArticle
...
delete:
tags:
- article
summary: Delete an article
operationId: deleteArticle
...
This OpenAPI spec fragment will generate the following directory structure:
..
\article
GET.yaml
POST.yaml
\_id
PUT.yaml
DELETE.yaml
Note that {id}
was transformed into _id
for file system compatibility.
Each file content is filled using the descriptorContent
function provided by the plugin.
Additionally, the generator creates a chillapi.lock.yaml
file with hashes for each file written. The purpose is to determine, on each subsequent run of the generate goal, whether the file was modified by the client app, in order to avoid overwriting custom content.
For the above example, the yaml would be:
chillapi:
- article:
- GET.yaml: xxxxxxxxxxxxxxx
- POST.yaml: xxxxxxxxxxxxxxx
- _id:
- PUT.yaml: xxxxxxxxxxxxxxx
- DELETE.yaml: xxxxxxxxxxxxxxx
When attempting to write a file in the directory structure, the generator will perform the following logic:
- IF the file does not exist, THEN write it and append the hash to the lock file.
- IF the file exists, THEN
- IF the file is present on the lock file, THEN
- calculate the hash of the existing file
- compare with the hash from the lock file
- IF hashes are equal (i.e. file was generated and not modified by client app), THEN overwrite it
- ELSE (file was modified by client app) skip
- ELSE (file was created by client app) skip
- IF the file is present on the lock file, THEN
Generate Server Implementation based on ChillAPI Config
Available options:
-
rootDirectory:string
: the location where the ChillAPI runtime should be saved; default./runtime
-
stepContent:function(step:any)=>{import:string,implementation:string}
: a function that takes a step, as defined by the plugin in the ChillAPI configuration and generates the import section required to execute the step, as well as the actual code to be executed inside the Server implementation method
Note that, in case the stepContent
function is missing, the import string will default to:
import {executeStep as myPluginName_executeStep} from 'myPluginName'
This assumes that the plugin exports a method with the signature executeStep(request, response, context)
The implementation will default to:
async function operation(request, response){
const context: any = {};
try{
//... other steps
// START IMPLEMENTATION DEFAULT
const result = await myPluginName_executeStep(request, response, context);
if(!!result){
response.ok(result);
return Promise.resolve();
}
// END IMPLEMENTATION DEFAULT
//...other steps
} catch(error){
response
.status(error?.status || 500)
.send(error?.content || "Unexpected error");
return Promise.resolve();
}
response.ok();
return Promise.resolve();
}
A few notes on the step execution:
- The first step that resolves to a non-undefined value also returns from the HTTP method;
- If the step wants to return an error status, it should reject with an error object containing
status
andcontent
- If a step wants to pass variables to the next steps, it should use the
context
object available in the context of the entire operation