Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

revelio-apidoc

0.1.1 • Public • Published

revelio-apidoc

Adapter to publish apidoc documentation to a Revelio site

Command line parameters

revelio-apidoc <path_to_configuration_file> <revelio_url> [configuration_name] [options]

  • path_to_configurationFile - File path to your configuration file
  • revelio_url - URL of your Revelio installation
  • configuration_name (optional) - Name of the configuration to use
  • options
  • --publicKey <publicKey> - Public API key. Only necessary if your Revelio server requires API key authentication
  • --secretKey <secretKey> - Secret API key. Only necessary if your Revelio server requires API key authentication

Configuration file

In order to publish documentation to Revelio, you need to create a Revelio configuration file. This contains information about how to read documentation from your code and how it should be shown in Revelio.

Basic file

{
    "url": "http://myapiurl.com",
    "targets": [ "../lib/endpoints", "../lib/otherEndpoints" ],
    "path": "Sample Group/My API/QA/v1.2.3"
}

Multiple configurations

 {
     "targets": [ "../lib/endpoints", "../lib/otherEndpoints" ],
     "configurations": {
         "DEV": {
            "url": "http://dev.myapiurl.com",
            "path": "Sample Group/My API/DEV/v1.2.3"
         },
         "QA": {
            "url": "http://qa.myapiurl.com",
            "path": "Sample Group/My API/QA/v1.2.3"
         },
         "PROD": {
            "url": "http://myapiurl.com",
            "path": "Sample Group/My API/PROD/v1.2.3"
         }
 }

Supported attributes

The following are standard apiDoc attributes that Revelio supports

  • @api {method} route description Required
  • Marks this as an endpoint with the given HTTP method and route.
  • Description is optional
  • Example: @api {get} /employee/:employee_id Gets an employee's information
  • @apiId endpoint_id Optional
  • Gives the endpoint an Id, unique per site. This helps track changes to the endpoint.
  • If none is provided, one will be generated
  • @apiName friendly_endpoint_name Optional
  • Gives the endpoint a name, otherwise apiDoc will attempt to give one based on the route
  • Example: @apiName GetEmployee
  • @apiGroup group_name Optional
  • Assigns the endpoint to a group, making it easier to navigate in the UI
  • Note:
  • @apiDescription Description text Optional
  • Gives this endpoint a description
  • Example: @apiDescription Gets an employee's information
  • @apiParam {type} field_name field_description Optional
  • Used to describe input for the endpoint: query string parameters for GET and DELETE, or a JSON object for POST and PUT. See below for examples
  • @apiSuccess (group_name) {type} field_name field_description Optional
  • Used to describe the response for a successful request. Similar to @apiParam. See below for examples
  • @apiError (group_name) {type} field_name field_description Optional
  • Used to describe responses for an erroroneous request. Similar to @apiSuccess. See below for examples
  • @apiIgnore Optional
  • This can be used to exclude an endpoint

The following are custom Revelio attributes

  • `@apiResponse (group_name) response_code response_description
  • Gives the HTTP response code and a semantic description for the group_name response
  • See examples below

GET request with response information

/**
 * @api {get} /employee/:employeeId Retrieves an employee by their ID
 * @apiName GetEmployee
 * @apiResponse (success) 200 User information
 * @apiSuccess (success) {String} firstName User's first name
 * @apiSuccess (success) {String} lastName User's last name
 * @apiSuccess (success) {Integer} id User's ID
 * @apiSuccess (success) {Object} contact
 * @apiSuccess (success) {String} phone
 * @apiSuccess (success) {String} email
 * @apiSuccess (success) {String} fax
 * @apiResponse(userNotFound) 404 User not found
 * @apiError (userNotFound) {String} error
 */

GET request with query string parameters

/**
 * @api {get} /employee Searches for employees by first and last name
 * @apiName ListEmployees
 * @apiParam {String} search Search terms
 * @apiParam {Int} page Page number
 * @apiParam {Int} pageSize Number of records per page
 * @apiResponse (success) 200 List of users matching the search terms
 * @apiSuccess (success) {Object[]} results
 * @apiSuccess (success) {String} results.firstName User's first name
 * @apiSuccess (success) {String} results.lastName User's last name
 * @apiSuccess (success) {Integer} results.id User's ID
 * @apiSuccess (success) {Integer} totalCount Total number of records returned
 */

POST request with JSON payload

/**
 * @api {post} /employee Create an employee
 * @apiName CreateEmployee
 * @apiParam {String} firstName User's first name
 * @apiParam {String} {String} lastName User's last name
 * @apiParam {String} {Object} contact
 * @apiParam {String} {String} phone
 * @apiParam {String} {String} email
 * @apiParam {String} {String} fax
 * @apiResponse (success) 200 User successfully created
 * @apiSuccess (success) {Integer} id User's Id
 * @apiResponse (invalidData) 400 Invalid data
 * @apiError (invalidData) {String[]} errors
 */

Custom parsers

Revelio supports using custom ApiDoc parsers to modify documentation. See the sample parser in examples/parsers/api_auth.js or refer to the apiDoc site for more information about creating parsers.

{
    "url": "http://myapiurl.com",
    "targets": [ "../lib/endpoints", "../lib/otherEndpoints" ],
    "path": "Sample Group/My API/QA/v1.2.3",
    "parsers": ["./parsers/custom_parser.js"]
}

install

npm i revelio-apidoc

Downloadsweekly downloads

3

version

0.1.1

license

MIT

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability