SwaggerTooth

Written in Typescript, this package is intended for generating sample requests & responses based on the supplied swagger yaml/json files.

SwaggerTooth fully supports $ref object references, complexly nested arrays and objects, allOf polymorphism when generating the samples.

Usage

Node.js and command line tool is available as well as a simple Angular-compatible class.

Node.js

Configurtations in file (e.g. swaggertooth.conf.json)

{
  sourceSwaggerPath: "some/folder/swagger.yaml", // any swagger file path
  outputFolderPath: "your/project/src/assets/swagger", // any folder
  
  angularServePath: "assets/swagger" // optional Angular support
}

const fs = require('fs');
const SwaggerTooth = require('swaggertooth').SwaggerTooth;
const swaggerToothConfig = SwaggerTooth.configFile('swaggertooth.conf.json');

const tooth = new SwaggerTooth(swaggerToothConfig);

tooth.generateExamples();

Command Line

npm i swaggertooth --save-dev
npx swaggertooth generate-example --input swagger.yaml --output my/folder

Sample Generation

openapi: 3.0.0
info:
  title: SwaggerTooth Test
servers:
  - url: /app
    description: base api path
paths:
  /test/{param}:
    post:
      requestBody:
        content:
          application/json: # supported: json, xml, yaml
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  my_id:
                    type: number
                  my_uuid:
                    type: string
                    format: uuid
                  endpoint:
                    type: string
                    format: uri
        400:
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    format: number
                  message:
                    type: string
                    format: uri
                    example: Reached Forbidden!

Above swagger file as source will output the following to the output folder:

// FILENAME: app.test.$param.post.request.json
{
  "email": "[email protected]"
}

// FILENAME: app.test.$param.post.response.200.json
{
  "my_id": 1,
  "my_uuid": "2ad75fdb-6e18-4107-a561-1dda9a14b5a9",
  "endpoint": "https://103.196.56.180:61045/test-e9a671"
}

// FILENAME: app.test.$param.post.response.400.json
{
  "status": "400",
  "message": "Reached Forbidden!"
}

If content type is set to application/xml:

<!-- app.test.$param.post.request.xml -->
<email>[email protected]</email>

<!-- app.test.$param.post.response.200.xml -->
<root>
  <my_id>1</my_id>
  <my_uuid>eb157a89-fb57-49b1-9aa1-f7200f754b0f</my_uuid>
  <endpoint>https://231.248.219.173:45884/test-7a906d</endpoint>
</root>

<!-- app.test.$param.post.response.400.xml -->
<root>
  <status>400</status>
  <message>Reached Forbidden!</message>
</root>

If content type is set to application/yaml:

# app.test.$param.post.request.yaml
email: [email protected]

# app.test.$param.post.response.200.yaml
my_id: 1
my_uuid: c978c555-b7de-4460-88a6-8625517117c7
endpoint: 'https://170.130.249.140:32434/test-6773f5'

# app.test.$param.post.response.400.yaml
status: '400'
message: Reached Forbidden!

The generation function will also output generation.info.json file to the output folder to provide information on what has been generated and what options were given to the tool.

{
  "info": {
    "totalPaths": 1,
    "totalItems": 3,
    "totalRequests": 1,
    "totalResponses": 2
  },
  "configs": { "sourceSwaggerPath": "test/api.yaml", "outputFolderPath": "output" },
  "traverseOptions": { "examplesPickFirst": true, "mock": true },
  "paths": {
    "POST /test/{param}": {
      "requests": [
        "app.test.$param.post.request.json"
      ],
      "responses": [
        "app.test.$param.post.response.200.json",
        "app.test.$param.post.response.400.json"
      ]
    }
  },
  "warnings": [],
  "errors": []
}

Angular Usage

You can generate samples to your static folder (e.g. assets/swagger), and fetch the generated sample requests and responses from Angular by using provided fetcher class called SwaggerToothAngular from swaggertooth/angular.js.

declare var require: any;
const SwaggerToothAngular = require('swaggertooth/angular.js').SwaggerToothAngular;
const swaggerToothConfig = require('swaggertooth.conf.json');
// config should have `angularServePath` value (default: 'assets/swagger')

const fetch = new SwaggerToothAngular(swaggerToothConfig);
fetch.sampleResponse('POST /test/{param}', 200)
  .then(sampleResponse => {
    /** sampleResponse: {
     *    my_id: 1,
     *    my_uuid: "ea2ad296-4419-4a9f-842a-a5a76bd516bd",
     *    endpoint: "https://166.46.112.210:58592/test-e60121"
     * } */
  });

fetch.sampleRequest('POST /test/{param}')
  .then(res => {
    // Some sample request
  });

// Function signatures:
// fetch.sampleRequest<T>(path: string, asString?: boolean = false): Promise<T>
// fetch.sampleResponse<T>(path: string, statusCode: number, asString?: boolean = false): Promise<T>

License

MIT