AzDoc

AzDoc is a simple endpoint documentation. This library allows easy and quick integration of endpoint documentation cases for use. In the new version, several modifications modifications were done to integrate Endpoint Test functionality. The Endpoint Test functionality is under validation yet.

Install

Install azdoc using the npm package manager:

npm install azdoc

1. Creating Documentation

1.1 Params Documentation

• description (string): Description of the endpoint

• method (string): Supported HTTP methods ("POST" | "GET" | "PUT" | "DELETE" | "ALL" | "PATCH")

• url (string): Endpoint address. Example (/api/products)

• tests (endpointTest[]): Object(s) of type endpointTest for implementing endpoint tests

1.2 Example Creating Documentation

In this example, documentation is created for an endpoint called getOne. The URL contains a placeholder {{productId}} that should be replaced with the product ID when making the request. In the next section, the implementation of the tests parameter will be detailed.

import { endpoint } from "azdoc";
import GetOne from "path/test/product/getOne";

export const getOne: endpoint = {
  description: "Get One Product by id",
  method: "GET",
  url: "/api/product/{{productId}}",
  tests: [
    GetOne.onSuccess,
    GetOne.error
  ]
};

1.3 Express Html Response

An asynchronous function named doc is exported. This function takes an argument router (Express router). The function creates a new instance of AzDoc named doc with the name 'Products'. It then adds a group to the documentation with the name "Product" and adds the previously defined getOne endpoint to this group. The function then generates the HTML documentation and stores it in the variable html.

Finally, the function defines a GET route for '/doc' on the router. When this route is accessed, it responds with the previously generated HTML documentation. The response is sent as a Buffer converted to UTF-8, and the content type of the response is set to 'text/html'.

import { AzDoc } from "azdoc";
import * as ProductMO from "path/module/doc/documentation";

let html = '';

export default async function doc(router) {
  const doc = new AzDoc('Products');

  doc.addGroup({
    name: "Product",
    endpoints: [
      ProductMO.getOne
    ]
  });

  html = doc.html();

  router.route('/doc').get((req, res) => {
    res.set('Content-Type', 'text/html');
    res.send(Buffer.from(doc.html(), 'utf-8'));
  });
}

2. Creating Test

2.1 Params Test

• name (string): Name of the test

• request? (object): Request to be made with parameters headers, params, body

  • headers? (object): Example access authorizations (user token)
  • params? (object): Parameters defined in the URL, for example: '/api/product/{{productId}}'
  • body? (object): Parameters defined in the request body

• response (object): Result of the server response, with parameters status, body, download, save

  • status (number): HTTP response status codes, for example: (200 | 500 | 502)

  • body? (object | any[]): Returns the properties of the object(s)

  • download? (string):

  • save? (object): Saves data properties of objects that can be used in future dependent tests. One of each type can be used: saveAll (saves all data of a particular variable), getOneInArray (saves objects that meet a certain condition), getProperty (saves a specific property of the object).

  • >>>>saveAll<<<<

    • var (string): Name of the variable that will be used in the future (contains all the data of the object)
    • method ("saveAll"): Method that will be used to save data

  • >>>>getOneInArray<<<<

    • var (string): Name of the variable that will be used (contains all the data of the object)
    • method Method that will be used to save data
    • where (object): Condition that must be met
    • property? (string): Property of the object that is filtered and will be saved in the 'var' property

  • >>>>getProperty<<<<

    • var (string): Name of the variable that will be used (contains all the data of the object)
    • method ("getProperty"): Method that will be used to save data
    • property (string): Property of the object that will be saved in the 'var' property

NOTE: The symbol "?" represents variables that are not mandatory.

2.2 Examples Creating Test

2.2.1 Example 1

In this example, a test has been implemented to return a successful request from the getAll endpoint ("/api/category/{{categoryId}}/product"). In the test, the user's token is added to the request header, and the response should return the parameters of the product object.

// Documentation 
// Endpoint getAll call GetAll on Success test

import { endpoint } from "azdoc";
import * as GetAll from "path/test/product/getAll";

export const getAll: endpoint = {
  description: "Get All Category Products",
  method: "GET",
  url: "/api/category/{{categoryId}}/product",
  tests: [
    GetAll.onSuccess
  ]
};

// Test
// Get All Products OnSuccess
import { endpointTest } from "azdoc";

export const onSuccess: endpointTest = {
  name: "On Success",
  request: {
    headers: {
      authorization: "{{token}}"
    }
  },
  response: {
    status: 200,
    body: [
      {
        id: "uuid",
        categoryId: "uuid",
        name: "string"
      }
    ]
  }
};

NOTE: The tests are called within the 'Test' parameter in the documentation.

2.2.2 Example 2

In this second example, a test is implemented for a successful product creation. In addition to the user's token, the name of the product is added to the body. The response will include the parameters of the product object, with the uuid from the database (in our example), the category id that should have been passed in the endpoint header, and the name of the new product.

The save parameter is also used in the response to save the id property of the object in the variable productId. This will allow using the value of the variable in subsequent tests.

// Documentation 
// Endpoint create call Create on Success test

**Here implementation endpoint create product**

// Test
// Create Product OnSuccess
import { endpointTest } from "azdoc";

export const onSuccess: endpointTest = {
  name: "On Success",
  request: {
    headers: {
      authorization: "{{token}}"
    },
    body: {
      name: "Product 01"
    }
  },
  response: {
    status: 200,
    body: {
      id: "uuid",
      categoryId: "{{categoryId}}",
      name: "Product 01"
    },
    save: {
      var: "productId",
      method: "getProperty",
      property: "id"
    }
  }
};

2.2.3 Example 3

In the third and final test, we perform an update of the product name by passing the new product name in the body. In the response, we receive the value of the variable (product id) saved from the previous test {{productId}}, the category id, and the new product name.

// Documentation 
// Endpoint update call update on Success test

**Here implementation endpoint update product**

// Test
// Update Product onSuccess
import { endpointTest } from "azdoc";

export const onSuccess: endpointTest = {
  name: "On Success",
  request: {
    headers: {
      authorization: "{{token}}"
    },
    body: {
      name: "Product 02"
    }
  },
  response: {
    status: 200,
    body:  {
      id: "{{productId}}",
      categoryId: "{{categoryId}}",
      name: "Product 02"
    }
  }
};

2.3 Run Tests

The appTest function creates a new instance of UnitTest named test. This instance is configured with a baseHeader object containing standard HTTP headers for accepting and sending JSON data. The base URL for the tests is set as http://localhost: followed by the value of the 'PORT' environment variable, or 3000 if 'PORT' is not defined.

Finally, the run function is called on the test object with an array of the previously imported objects. This function executes the test(s) for each of the endpoints represented by these objects. Since the run function is asynchronous, it is called with await to ensure that the appTest function waits until all tests are completed before continuing.

import { getEnv } from "aztool";
import * as ProductMO from "path/module/doc/documentation";


async function appTest() {

  const test = new UnitTest();

  test.baseHeader = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  };

  test.baseUrl = `http://localhost:${getEnv('PORT', 3000)}`;

  await test.run([
    ProductMO.getAll,
    ProductMO.create,
    ProductMO.update
  ]);

}