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 filerevelio_url
- URL of your Revelio installationconfiguration_name
(optional) - Name of the configuration to useoptions
--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
Multiple configurations
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 * @apiName GetEmployee * @apiResponse (success) 200 User information * @apiSuccess (success) * @apiSuccess (success) * @apiSuccess (success) * @apiSuccess (success) * @apiSuccess (success) * @apiSuccess (success) * @apiSuccess (success) * @apiResponse(userNotFound) 404 User not found * @apiError (userNotFound) */
GET request with query string parameters
/** * @api * @apiName ListEmployees * @apiParam * @apiParam * @apiParam * @apiResponse (success) 200 List of users matching the search terms * @apiSuccess (success) * @apiSuccess (success) * @apiSuccess (success) * @apiSuccess (success) * @apiSuccess (success) */
POST request with JSON payload
/** * @api * @apiName CreateEmployee * @apiParam * @apiParam * @apiParam * @apiParam * @apiParam * @apiParam * @apiResponse (success) 200 User successfully created * @apiSuccess (success) * @apiResponse (invalidData) 400 Invalid data * @apiError (invalidData) */
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.