API Documentation Formatting Library

Meteor Platform API Documentation Formatting Library w/ Swagger.

Installation

npm i git+ssh://[email protected]/mtr-platform/libs/apidoc#v1.0.7

Penggunaan

Buat file doc.js di dalam root folder atau index.js di dalam folder doc dengan format seperti berikut:

const description = 'API description';
const schemes = ['https', 'http']; // Options are https & http
const tags = [
  {
    name: 'Tag Name',
    description: 'Tag description.',
  },
];
const paths = {
  'path-name': {
    get: { // Method type, options are get, post, put & delete
      tags: ['Tag Name'],
      description: 'Endpoint description',
      auth: true, // If set true then will add an Authorization field on headers
      dataTable: [ // Will automatically generate basic query parameters
        { name: 'id', searchable: true },
        { name: 'name', searchable: true },
        { name: 'phone', searchable: true },
        { name: 'email', searchable: true },
      ],
      parameters: [ // Can be used to add additional query parameters
        {
          name: 'status',
          in: 'query',
          type: 'string',
          default: '',
          description: 'Index only specific status',
        },
      ],
      results: {
        200: {
          total: 1,
          total_filtered: 1,
          total_displayed: 1,
          total_page: 1,
          page: 1,
          data: [
            {
              id: '3ec79570-75f7-11e9-8901-3778b1fc30d4',
              name: 'John Doe',
              phone: '88801426139',
              email: '[email protected]',
            },
          ],
        },
      },
    },
  },
  '/path-name/{id}': {
    post: {
      tags: ['Tag Name'],
      description: 'Endpoint description',
      auth: true,
      parameters: [
        {
          name: 'id',
          in: 'path',       // Options are path, query, header & formData
                            // If value is 'path' then the parameter's name must exist in the endpoint,
                            // in this example is 'id' on '/path-name/{id}'
          type: 'string',   // Options are string, number, integer & boolean
          required: true,   // If not set then the field parameter is optional
          default: '2017ace8-3785-11ea-b295-84ef18e0817f',
          description: 'Parameter description',
          validation: ['Not empty', 'ID is in pathIDs'], // Validation set on API, free test
        },
      ],
      results: {
        200: {
          id: '23b97ce8-1944-11e9-9620-d5ae65e64e7e', // String
          int: 1579586389,                            // Number
          arr: ['OK', 'YES'],                         // Array
          obj: { ok: 1, no: 0 },                      // Object
          is: true,                                   // Boolean
        },
        403: {
          auth_token: {
            value: 'jwt expired',
            msg: 'TokenExpiredError',
          },
        },
      },
      // Possible response code, options are 200, 400, 401, 403, 500
      // Response code value can be in String, Number, Object or Boolean
    },
  },
};

module.exports = {
  description, schemes, tags, paths,
};

Deklarasikan module library di dalam file xxx-gateway/api.js.

const jsonDoc = require('mtr-apidoc');

module.exports = (router) => {
  router.get('/', jsonDoc);
};