[BETA] - gerJs
Create Swagger documentation from Joi models
Example for Koa : https://github.com/dobobaie/example-koa-gerjs-server
Example for Express : https://github.com/dobobaie/example-express-gerjs-server
Help us to improve the project by contributing 👥
☁️ Installation
$ npm install gerjs-core
📝 Usage
Initialization
Create a new instance :
const modelsAPI = ;const gerJs =swagger:title: "Swagger title"description: "Swagger description"servers_url: "http://apiUrl/"vesion: "1.0.0"destinationPath: "/path"modelsAPI;
📋 Instance options
swagger:title: "Swagger title" // string ; default: Swagger documentationdescription: "Swagger description" // string ; default: Retrieve all information from the API inside this documents.servers_url: "http://apiUrl/" // Array<string> ; default: ['http://locahost:8000/']vesion: "1.0.0" // string ; default: "1.0.0"destinationPath: "/path" // string ; required
⚙️ Model examples
Joi
is required to create the models
const Joi = ;const refs =token:Joiobjecttoken: Joilabel"token"classic:Joiobjectmessage: Joiresult: Joilabel"classic";const models ='POST/register':description: 'Register route'tags: // tags are generate automaticly but you can customize them"register"body:Joiobjectusername: Joidescription`Username of the user`firstname: Joidescription`Lastname of the user`lastname: Joidescription`Lastname of the user`extra: refsclassictest: Joicreated: Joistatus: Joidescription"Body description"response: refsclassicdescription"Extra register description for the response with a reference"'PUT/users/:id':queries: refstokenbody:Joiobjectusername: Joipassword: Joiresponse: refsclassicdescription'Extra description for the response with a reference''GET/':queries: refstokenresponse: Joidescription'...'// ORresponse: Joidescription'...';moduleexports = models;
Usage Model
// METHOD + ROUTE'{POST|GET|PUT|DELETE|...}{route: / | /hello | /...}':description: String // default: emptytags: Array<String> // default: automaticqueries: Joi // optionalbody: Joi // optionalresponse: Joi // required
Usage Refs
This is classic Joi
declaration. But label(String)
is required to make a link between each same refs.
For example :
const Joi = ;const refs =token:Joiobjecttoken: Joilabel"token";
As you can see refs.token
own token
label from .label("token")
declaration.
So everytime refs.token
will be called, the token decaration will be referenced in the same reference in the Swagger file.
If you don't specified the label
declaration then another reference will be created with another specific name.
Content-Type
Specify The Content-type
is automaticly determined by the Joi
declaration.
Ex: Joi.object(...)
is application/json
.
About the response
part, you can determined the Content-Type
directly in the meta
declaration.
Ex: response: Joi.any().meta({ "Content-Type": "text/plain" })
the route return a Content-Type
type text/plain
.
👥 Contributing
Please help us to improve the project by contributing :)
❓️ Testing
Clone the repo and run from the project root:
$ npm install
$ npm test