01 - Swagger editor

Owned by Antoine Hage (Unlicensed)
Last updated: Dec 05, 2017 by Michel El Hajj (Unlicensed)
3 min read

Introduction

This page provides instructions on how to use the Swagger Generator Module in SOAJS Dashboard UI to generate a microservice by simply providing the main information it needs and a SWAGGER YAML CODE.

The module offers 2 forms:

  • Service information
  • Swagger UI editor

The Module also provides inline documentation and guidelines for each input and its usage.

Service Information

Provide the information needed beside the yaml code to create a microserivce. The information is used later on to generate the content of config.js file, which is the main configuration file that every SOAJS microservice requires.

The information in this form is not supported by the Swagger UI Editor.

Red inputs are required, they will turn to green if the input is filled and matches the requirements.

  1. You can add multiple databases and provide a model for each database.
  2. Model files are automatically generated with their content.
  • Use a unique service name for each new service.
  • Choose a unique port for each service.
  • The es database model can't be created as a multitenant database so the multi-tenancy is disabled automatically for that database type.
  • Go to Swagger Documentation tab and provide a valid swagger YAML code then click the RUN button and the Swagger Engine will render the code.



Swagger UI Editor

This part of the form is divided to two sections: UI Code Editor - Swagger UI Generator

Start writing your APIs Documentation as Swagger Yaml Code in the editor; you will notice that a a green button "Run" will appear at the top right corner of the form.

Once you finish writing your code, press Run and the Swagger UI Generator will render the code.

The Swagger UI Generator won't render the documentation code unless that code follows the swagger specification standards and is well indented. Visit the swagger specification page to learn more.

If you made any change to your code, press Clear to clear the right section and press Run again to validate and render the documentation once again

  • Make sure to start your code with : swagger: "2.0"
  • Define the info tag that should contain at least a title and a version
  • No API can have multiple parameters passed in the body (Swagger Restriction)
  • Each API must have a summary (SOAJS Restriction)

At this stage if the user wants to use the swagger ui editor to test his APIs, and since the service is not deployed yet in any environment, all calls will be made to a dashboard API providing the input configuration of that API and the later will simulate the API behavior.

The dashboard API "simulate" will return true if everything is in order or an error in the case of imfv conflict.

Empty SwaggerRun code

Valid IMFV responseWrong IMFV response