Source’s File Format

ApiDoc uses source file(s) to generate the documentation. The format of the source file can be YAML or JSON, the extension of the files must be repectively .yaml (or .yml) or .json

This is a basic sample of a config file

configuration:
  title: Hello API
  description: An API dedicated to the hello service
  uri: ${base_url}
categories:
  Display:
    description: Display messages
  Config:
    description: Configure the application
versions:
  v1.0:
    methods:
      Hello:
        category: Display
        uri: /
        description: Say hello
        response_body:
          type: string
          sample: Hello
      HelloName:
        category: Display
        uri: /{name}
        request_parameters:
          name:
            type: string
            description: Name of the user
        request_headers:
          Accept:
            type: mimeType
            description: List of accepted MimeTypes
            sample: text/plain
        response_body:
          type: string
          sample: Hello my_name
      ConfigHello:
        category: Config
        uri: /
        method: PUT
        description: Configure the hello method
        request_body:
          type: object
          properties:
            language:
              type: string
              sample: "fr"
        response_body:
          type: boolean
    types:
      mimeType:
        item:
          type: string
          sample: application/json
        format:
          pretty: type/sous-type
  v2.O:
    status: beta
    display: false

All elements are optional, but a least one displayable method is required.

configuration

The configuration contains major information of your documentation.

  • uri: Common URI of your API (ie: https://api.sfr.com/service/)
  • title: The name of your API. It will be displayed in the title tag, and in the header of the documentation
  • description: A description of your API. It will be displayed under the title in the header of the documentation

sample:

configuration:
  title: Hello API
  description: An API dedicated to the hello service
  uri: https://api.sfr.com/services/hello

versions

This element contains a dictionary of versions. Each version is associated with a key which is the name of the version. At least one version is required.

  • display: Boolean Defining if the version is displayed or not.
  • label: The label of the version who will be display in the documentation.
  • uri: Completes the URI of the element configuration.
  • major: Major part of the version number.
  • minor: Minor part of the version number.
  • status (current, beta, deprecated, draft): Status of the version.
  • methods: List of methods contained in the version (see methods).
  • types: List of types contained in the version (see types).
  • references: List of references contained in the version (see references).

sample:

versions:
  v1.0:
    display: true
    label: Version 1
    uri: /v1
    major: 1
    minor: 0
    status: current
    methods:
      ...
  v2.0:
    display: false
    uri: /v2
    major: 2
    minor: 0
    status: beta
    methods:
      ...

categories

This element contains a dictionary of categories; a category is a kind of folder in the rendered documentation. Each category is associated to a key which is the name of the category. This elements is not required. A method (or a type) can have an attribute category which does not exist in this dictionnary. But this element allows you to configure the category by giving a description or a priority order.

  • display: Boolean defining if the category is displayed or not
  • label: The label of the category who will be display in the documentation
  • description: A description of the category. It will be dislayed under the name of the category
  • order: A number used to sort the categories and define in which order they will be displayed. Default value is 99. When two categories have the same order, they will be sorted alphabetically by name.

sample:

categories:
  Common:
    display: false
    description: a helper section use for extension
  Version:
    description: List the version of the API
    order: 1
  Authentication:
    label: Authentication + Logout
    description: How to login and logout the client

methods

This element contains a dictionary of methods. Each method is associated with a key which is the name of the method. At least one method is required.

  • label: The label of the method who will be display in the documentation.
  • description: A description of the method. It will be dislayed under the name of the method.
  • uri: Endpoint of the method based on the URI found in configuration and version. Parameters are declared between curly bracket.
  • method (get, post, put, delete, head, http): Type of method used in this endpoint (default get).
  • code: Normal code returned by the method (default 200). This information will be displayed in the sample generated in the documentation.
  • request_parameters: List of parameters sent in the URI of the method (see request_parameters).
  • request_headers: List of parameters sent in the headers of the method (see request_headers).
  • request_body: Request object sent in the body of the method (see request_body).
  • response_codes: List of codes received in the headers of the method (see response_codes).
  • response_body: Response object received in the body of the method (see response_body).
  • category: The name of the category to which the method belongs.

sample:

methods:
  Hello:
    label: Echo
    uri: /hello-{name}.json
    method: get
    code: 200
    description: Say hello
    request_parameters:
      ...
    request_headers:
      ...
    request_body:
      ...
    response_codes:
      ...
    response_body:
      ...

request_parameters

This element contains a dictionary of query parameters contained in the URI. Each parameter is associated with a key which is the name of the parameter. If a parameter is defined in this elements but is not on the URI, it will not be displayed. This can be usefull when you use extensions. The parameters will be displayed in the same order as they appear in the URI

  • type: Type of the parameter (see types).
  • description: A description of the parameter.
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • sample: A sample value which will be displayed in the sample fieldset.
  • generic: If true, the parameter will be displayed in an other color. Default False.

sample:

request_parameters:
  name:
    type: string
    description: Name of the user
    optional: false
    sample: John Doe
    generic: false
  language:
    type: string
    description: Language of the response
    optional: true
    sample: fr
    generic: true

request_headers

This element contains a dictionary of header parameters expected by the method. Each parameter is associated with a key which is the name of the parameter.

  • type: Type of the parameter (see types).
  • description: A description of the parameter.
  • optional: A boolean indicated if the parameter is compulsory or optional.
  • sample: A sample value which will be displayed in the sample fieldset.
  • generic: If true, the parameter will be displayed in an other color. Default False.

sample:

request_headers:
  Accept:
    type: mimeType
    description: List of accepted MimeTypes
    sample: text/plain
    optional: true
    generic: true
  X-Auth-Token:
    type: string
    description: Authentication token

request_body

This element contains an object which represents the raw content sent in the body of the request (see Objects).

sample:

request_body
    type: object
    description: Root envelope
    properties:
      login:
        type: string
      password:
        type: string

response_codes

This element contains a list of reponse codes returned by the method.

  • code: The numeric code returned in the response
  • message: A message associated to the response. When omitted, the default message associated with the code will be used
  • description: A description of the response
  • generic: If true, the parameter will be displayed in an other color. Default False

sample:

response_codes:
- code: 400
  message: Bad name format
  description: The resource name is not correct
- code: 404
  message: Resource not found
  generic: true

response_body

This element contains an object which represents the response received in the body of the response (see Objects).

sample:

request_body
  type: array
  description: List of users
  items:
    type: object
    properties:
      name:
        type: string
        description: Name of the user
      role:
        type: CustomRole
        description: Role of the user

types

This element contains a dictionary of types used by other elements. Each reference is associated with a key which is the name of the type. When a type is declared but never used, a warning will be fired in the logs and the type will not be displayed.

  • category: The name of the category to which the type belongs.
  • description: A description of the type.
  • item: The content of the type (see Objects).
  • format: Some representations of the type.
    • pretty: A well formated representation of the type.
    • advanced: A technically accurate representation of the type.

sample:

types:
  mimeType:
    category: Common
    description: A mime type
    item:
      type: string
      sample: application/json
    format:
      pretty: type/sous-type
      advanced: [a-z]\/[a-z]
  languages:
    category: Lists
    description: List of supported language
    item:
      type: enum
      values:
      - en
      - fr
      descriptions:
        en:
          description: English
        fr:
          description: Français

references

This element contains a dictionary of references used by objects. Each reference is associated with a key which is the name of the reference. The reference is not displayed directly, it is a complex object which could be used in other elements.

sample:

methods:
  listComments:
    ...
    response_body:
      type: array
      items:
        type: reference
        reference: comment
reference:
  comment:
    type: object
    properties:
      owner:
        type: reference
        reference: user
      message:
        type: string
      date:
        type: string
  user:
    type: object
    name:
      type: string
    language:
      type: string

Objects

In the bodies of types, requests and responses you can define a complex object using basic elements. These elements (defined below) contain always a keyword “type” which defines the type of the element. The known types, are object, array, dynamic, boolean, none, string, number, integer, reference, const, enum. If the type is not in this list, ApiDoc will look in the elements declared in the types section (see types). Each elements contains an attribute optional indicating if the element is compulsory or optional. They also contains an attribute constraints containing a dictionnary constraints. Some constraints are predefined depending of the type of the element, but it”s also possible to define custom constraints (a reference to yout business model for example). No check will be applied on sample according to these constraints, they only will be display in a popover in the rendered documentation. These constraints are derived from Json Schema

String

The object String defines a string.

  • description: A description of the string
  • sample: A sample value which will be displayed in the sample fieldset.
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • maxLength: A positive integer is expected.
  • minLength: A positive integer is expected.
  • pattern: A string is expected. It who should be a regular expression, according to the ECMA 262 regular expression dialect.
  • format: A string is expteced. It must be one of the values ​​found in this list (date-time, email, hostname, ipv4, ipv6, uri).
  • enum: An array of string is expected.
  • default: A string is expected.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

name:
  type: string
  description: Name of the user
  sample: John Doe
  minLength: 1
  maxLength: 32

Number

The object Number defines a numeric value with optionals decimals.

  • description: A description of the number
  • sample: A sample value which will be displayed in the sample fieldset.
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • multipleOf: A number is expected.
  • maximum: A number is expected.
  • exclusiveMaximum: A boolean is expected.
  • minimum: A number is expected.
  • exclusiveMinimum: A boolean is expected.
  • enum: An array of number is expected.
  • default: A number is expected.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

price:
  type: number
  description: Price in dollars
  sample: 20.3
  maximum: 0
  multipleOf: 0.01

Integer

The object Integer defines a numeric value without decimal.

  • description: A description of the number
  • sample: A sample value which will be displayed in the sample fieldset.
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • multipleOf: A integer is expected.
  • maximum: A integer is expected.
  • exclusiveMaximum: A boolean is expected.
  • minimum: A integer is expected.
  • exclusiveMinimum: A boolean is expected.
  • enum: An array of integer is expected.
  • default: A integer is expected.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

age:
  type: number
  description: Age of the user
  sample: 20
  maximum: 0

Boolean

The object Boolean defines a boolean.

  • description: A description of the boolean
  • sample: A sample value which will be displayed on the sample fieldset.
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • default: A boolean is expected.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

is_default:
  type: boolean
  description: Define if the group is the default group
  sample: false
  default: false

None

The object None defines an empty object. Sometime used in a request when a key is compulsory but no value is expected.

  • description: A description of the object
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

reboot:
  type: none
  description: Set this key if you want reboot your server
  constraints:
    compulsory: yes

Const

The object Const defines an constant property. Sometime used in a request like the property “method” in Json-RPC.

  • description: A description of the object
  • cont_type: A scalar type of the constant (allowed values are string, number, integer, boolean). If undefined string will be used
  • value: The value associated to the property
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

method:
  type: const
  description: Json-RPC method name
  const_type: string
  value: "find"
  constraints:
    required: authenticated user

Enum

The object Enum defines a list a availables values. When this object is the primary object of an type (see types) the values with there descriptions will be displayedin the Type section.

  • description: A description of the object
  • values: An array of values
  • descriptions: A dictionnary of description for each value
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

httpMethods:
  type: enum
  description: List of Http methods used in Rest
  values:
  - GET
  - POST
  - PUT
  - DELETE
  descriptions:
    GET: Like select
    POST: Like insert
    PUT: Like update
    DELETE: Like delete
  sample: GET
  constraints:
    required: authenticated user

Object

The object Object defines a complex object containing a dictionnary of properties, patternProperties or additionalProperties. Each property is associated with a key which is the name of the property.

  • description: A description of the object
  • properties: List of properties of the object
  • patternProperties: List of properties of the object where the key is a regular expression
  • additionalProperties: A boolean False when additional properties are not allowed, Otherwise it’s an object
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

element:
  type: object
  description: User to update
  properties:
    name:
      type: string
      description: New name of the user
    metadata:
      type: object
      additionalProperties:
        type: string
  constraints:
    required: authenticated user

Array

The object Array defines an array of objects.

  • description: A description of the array
  • items: A representation of the items contained in the array
  • sample_count: Number of items to display in the sample fieldset
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • maxItems: A positive integer is expected.
  • minItems: A positive integer is expected.
  • uniqueItems: A boolean is expected.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

elements:
  type: array
  description: List of users
  items:
    type: object
    properties:
      name:
        type: string
        description: New name of the user
  maxItems: 10

Reference

The object Reference defines a reference to a referenced object. Reference is the only one elements who does not have constraints. This constraints are defined in the refererenced item.

  • reference: Name of the reference
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.

sample:

user:
  type: reference
  reference: GenericUser

Dynamic (deprecated)

The object Dynamic defines a special object where the key, which must be a string, is dynamic. You should use object with additionalProperties instead of this dynamic element.

  • description: A description of the array
  • items: A representation of the items contained in the object
  • sample: A sample value which will be displayed on the sample fieldset.
  • optional: A boolean indicating if the parameter is compulsory or optional. Default False.
  • maxItems: A positive integer is expected.
  • minItems: A positive integer is expected.
  • constraints: A dictionary of constraints * {constraint_name}: A string is expected

sample:

metadatas:
  type: dynamic
  description: A list of key/value to store what you want
  item: string

Customizations

Variables

Variables can be provided by command line arguments or in the config file (see input). Each value of the source file can be (or contain) a variable.

Sample using a variable string context:

configuration:
  title: ${applicationName}
  description: Official documentation of ${applicationName}

Sample using a variable to set a boolean:

categories:
  MyExperiments:
    display: ${displayExperimentals}

Sample using a variable used in extends context:

versions:
  v1:
    ...
  v2:
    extends: ${officialVersion}

Extends

ApiDoc provides a way to simplfy source files writing by using an extends system. You can extend your versions, categories, methods, types and references. To extend an element you only have to specify the name of referenced elements with extends: referenced_name. The referenced name is always of the same type as your elements (a version extends a version, a method extends a method, etc…). If the referenced element is a sibling of the current element, you can just specify its name, if the reference does not belong to the same parent, you must then specify the name of the parent followed by a /. For exemple, if your methods A and B belong to different versions you must use extends: version_of_b/method_b for method A to extend method B. Extensions are recursive, but you can break recursion on any element by using inherit: false and you can remove an element with removed: true.

Sample using an extension on the version:

versions:
  v1:
    ...
  v2:
    extends: v1

Sample using an extension on a method with relative path and absolute path:

versions
  v1:
    methods:
      Request:
        ...
      AuthenticatedRequest:
        extends: Request
  v2:
    methods:
      Login:
        extends: v1/Request

Sample using an extension where the method ListClientWithDetails extends ListClients but not for the response_body which is redefined:

methods:
  ListClients:
    ...
  ListClientWithDetails:
    extends: ListClients
    response_body:
      inherit: false
    ...

Sample using an extension where the section SessionAuthentication extends FormAuthentication but the content of the body of the method Login is removed:

methods:
  Login:
    request_body:
      type: object
      properties:
        login:
          type: string
        password:
          type: string
  SSO:
    extends: Login
    request_parameters:
      token_id:
        type: string
    request_body:
      removed: true

You can extend multiple elements by providing an list of extensions.

Methods:
  Authenticated:
    request_header:
      X-Auth-Token:
        type: string
  Paginated:
    request_parameter:
      index:
        type: integer
      limit:;
        type: integer
  Customers:
    extends:
    - Authenticated
    - Paginated