v0.1.md

apiDoc Specification

Version 0.1

This file describes the format that is returned by apidoc.

Format

apidoc response is represented as a JSON object and Javascript AMD Modul.

apidoc itself copy some template files to the destination dir too. Only when lib/apidoc is directly included and parameter --parse=true is set, the json and javascript files will be returned.

JSON:

{
  "name": "apidoc-example",
  "version": "0.3.0",
  "description": "apiDoc example project",
  "generator": {
    "version": "0.7.1",
    "time": "2014-08-22T16:15:45.522Z"
  }
}

Javascript AMD Modul:

define({
  "name": "apidoc-example",
  "version": "0.3.0",
  "description": "apiDoc example project",
  "generator": {
    "version": "0.7.1",
    "time": "2014-08-22T16:15:45.522Z"
  }
});

Response

By default apidoc creates 4 files:

• api_data.json / api_data.js with the representation of the API
• api_project.json / api_project.js with the project description and documentation settings

Schema api_data

Example api_data

Example file

Data array

The api_data root is an array that contain a list of objects (Endpoints).

Name	Type	Description
object	Endpoint	Unique Endpoint.

Endpoint object

Each Endpoint / Method is unique. Unique because of their group, name and version, not because of the url, the url can change while the api is in development.

Name	Type	Description
group	string	Group of the endpoint. A group describe to which part of your application the endpoint belongs, e.g. GET /user/:id/ and POST /logout could belong to the group Account. In the default template the group is used to separate the endpoints under a main navigation point. Example: "User"
name	string	Name of the endpoint. Example: "GetUser".
version	string	Version of the endpoint - semver 2. If no Version is supported set to "0.0.0". Example: "0.3.0"
type	string	Type of the endpoint. "get", "put", "post", "delete", ...
url	string	Endpoint path, a relative path to the projects base url. Example: "/with/:id/do/something"
title	string	Title of the endpoint.
description	string	Endpoint description. HTML capable.
groupDescription	[string]	Group description. HTML capable.
filename	string	Relative filename of the documentation position in the source file.
permission	[Permission]	Permission object.
parameter	[Parameter]	Parameter object.
success	[Success]	Success object.
error	[Error]	Error object.
header	[Header]	Header object.
examples	[Examples]	List of examples.
sampleRequest	[SampleRequest]	List of sample request objects, to test the the API.

Permission object

Describes the permissions to access the endpoint.

Name	Type	Description
name	string	Name of the permission. Example: "admin"
title	string	Title of the permission. Example: "Admin access rights needed."
description	string	Permission description. HTML capable.

Parameter object

Contains information about the parameters transfered to the endpoint.

Name	Type	Description
fields	Fields	Fields object.
For historical reasons, the Parameter object did not have an examples array (compared to the Success, Error, Header object).

Success object

Contains information about the success response from the server.

Name	Type	Description
fields	Fields	Fields object.
examples	Examples	Examples array.

Error object

Contains information about the error response from the server.

Name	Type	Description
fields	Fields	Fields object.
examples	Examples	Examples array.

Header object

Contains information about the header transfered to the endpoint.

Name	Type	Description
fields	Fields	Fields object.
examples	Examples	Examples array.

Examples array

A list of objects that contain examples to access the Endpoint.

Name	Type	Description
object	Example	Example object.

Sample Request array

A list of objects that contain sample URL to test the Endpoint from within the documentation.

Name	Type	Description
object	Example	Sample Request object.

Example object

Example to access the Endpoint.

Name	Type	Description
title	string	Title of the example. Example: "Example usage with CURL:"
content	string	Example code to access the endpoint.
type	[string]	The code style of the content: "curl", "json", "yaml", ...

Sample Request object

Test the Endpoint from within the documentation.

Name	Type	Description
url	string	URL of the Endpoint.

Fields object

Contains variable named arrays. The label is the group of a field (more exactly the label of a group).

The label could be empty "", if no grouping is needed.

Name	Type	Description
label	Field	Field object.

Example: "This is a group" is the variable label

"fields": {
  "This is a group": [
    {
      "group": "MyGroup",
      "type": "String",
      "field": "id",
      "optional": false,
      "description": "<p>The Users-ID.</p>"
    }
  ]
}

Hint: Yes it was a stupid idea, it was implemented because of the simpler processing in the handlebar template and will definitely changed in a future version.

Field object

A single parameter field.

Name	Type	Description
group	string	Group name of the field. The group is used for a grouped output of all fields that belong to a group, e.g. it can be used to show public and private fields.
type	string	User defined field type, "String", "Number", "Boolean"
field	string	Name of the. Example: "firstname"
optional	boolean	Is the field optional.
defaultValue	mixed	The default value of the field.
description	string	Description of the field. HTML capable.

Schema api_project

Example api_project

Example file

{
  "name": "apidoc-example",
  "version": "0.3.0",
  "description": "apiDoc example project",
  "title": "Custom apiDoc browser title",
  "url": "https://api.github.com/v1",
  "sampleUrl": "https://playground.github.com/v1",
  "generator": {
    "version": "0.7.1",
    "time": "2014-08-22T16:15:45.522Z"
  },
  "template": {
    "withCompare": true,
    "withGenerator": true
  },
  "header": {
    "title": "Introduction",
    "content": "<p>Please visit <a href=\"http://apidocjs.com\">apidocjs.com</a> for the full documentation.</p>\n"
  },
  "footer": {
    "title": "Epilogue",
    "content": "<p>Suggestions, contact, support and error reporting on <a href=\"https://github.com/apidoc/apidoc/issues\">GitHub</a></p>\n"
  }
}

Project object

Name	Type	Description
name	string	Name of the application.
version	string	Version of the application (not the apiDoc Specification or Generator version!) - semver 2. Example: "0.3.0"
description	string	Project description. It is used as introduction at the beginning of the documentation.
title	[string]	Browser title.
url	[string]	Public URL to access the API (prefix URL for an endpoint). Example: "https://api.github.com/v1"
sampleUrl	[string]	Public URL to test the API. Example: "https://playground.github.com/v1"
generator	[Generator]	Provides generator informations.
template	[Template]	Template specific settings.
header	[Header]	Additional content for the top of the documentation.
footer	[Footer]	Additional content for the bottom of the documentation.

Generator object

Provides generator informations.

Name	Type	Description
version	string	Version of the generator (not the apiDoc Specification version!) - semver 2. Example: "0.7.1"
time	string	Date-time when the representation file was created - ECMA-262. Example: "2014-08-22T16:15:45.522Z"

Template object

Template specific settings. This settings belong to the default template.

Name	Type	Default	Description
withCompare	[boolean]	true	Enable version compare function.
withGenerator	[boolean]	true	Append generator information at the bottom of the page.

Header object

An optional introduction section. The usage depend on the template.

Name	Type	Default	Description
title	[string]	"General"	The title is used as the navigation label in default template.
content	[string]	""	HTML content appended to the top of the documentation.

Footer object

An optional epilogue. The usage depend on the template.

Name	Type	Default	Description
title	[string]		The title is used as the navigation label in default template.
content	[string]		HTML content appended to the bottom of the documentation.