Skip over navigation
Documentation
You are currently viewing documentation for a previously released version of OroCommerce. See the latest long-term support version.

Documenting API Resources

Overview

You need to provide detailed documentation for your API resources because it is an important part of API and it could help a lot to developers to use your API.

OroPlatform collects documentation for API resources from several sources:

The most priority source is the configuration file. The documentation provided there overrides all other sources. But as it is YAML file it is not the best way to write big multi-line texts there. The more appropriate place for the documentation is a separate Markdown file. To use such file you need to provide a link to it in the configuration file, e.g.:

api:
    entities:
        Acme\Bundle\AppBundle\Entity\AcmeEntity:
            documentation_resource: '@AcmeAppBundle/Resources/doc/api/acme_entity.md'

If the documentation was found neither the configuration file nor the documentation file, the Oro Platform will try to use system-wide descriptions of entities and fields. These descriptions are usually provided in translation files and, actually, they are the best way to document fields, because these descriptions can be used not only in API. Here is an example of a translation file contains descriptions for entities and fields:

# Acme/Bundle/AppBundle/Resources/translations/messages.en.yml
oro:
    sales:
        #
        # Opportunity entity
        #
        opportunity:
            entity_label:         Opportunity
            entity_plural_label:  Opportunities
            entity_description:   The Opportunity represent highly probable potential or actual sales to a new or established customer
            id.label:             Id
            name:
                label:            Opportunity name
                description:      The name used to refer to the opportunity in the system.
            close_date:
                label:            Expected close date
                description:      The expected close date for open opportunity, and actual close date for the closed one
            probability:
                label:            Probability
                description:      The perceived probability of opportunity being successfully closed

Please note that after changing a documentation you need to run oro:api:doc:cache:clear CLI command to apply the changes to API sandbox.

Documentation File Format

The documentation file is a Markdown document that contains description about one or multiple API resources. Please note that the Markdown Extra syntax is supported in the documentation file as well.

The only requirement for such document is it should be written in particular format.

Each resource documentation should starts from ‘#’ (h1) header that contains Fully-Qualified Class Name (FQCN) of the resource, e.g.:

# Acme\Bundle\AcmeBundle\Entity\AcmeEntity

As already mentioned above, a single documentation file may contain documentations for several resource. In general, this can be used to document a main resource and related resources. For example, you can document resources for User and UseStatus entities in one file.

At the next level ## (h2) one of the documentation sections should be specified, e.g.:

# Acme\Bundle\AcmeBundle\Entity\AcmeEntity

## ACTIONS
...
## FIELDS
...
## FILTERS
...
## SUBRESOURCES
...
The section name is case insensitive. They are used only by documentation parser to identify the documentation part.
The following table describes the purposes of each documentation section:
Section nameDescription
ACTIONSContains a documentation of actions.
FIELDSContains a description of fields.
FILTERSContains a description of filters.
SUBRESOURCESContains a documentation of sub-resources.

The third level ### (h3) header depends on the section type and can be action name, field name, filter name or sub-resource name.

The fourth level #### (h4) header can be used only for FIELDS and SUBRESOURCES sections. For FIELDS section it can be used for the case when it is needed to specify the description for a field in a particular action. For SUBRESOURCES section it is a sub-resource action name.

The action names in FIELDS section can be combined using comma, e.g.: “Create, Update”. It allows to avoid copy-paste when you need the same description for several actions.

An example:

# Acme\Bundle\AcmeBundle\Entity\AcmeEntity

## ACTIONS

### get

The documentation for an action, in this example for "get" action.
May contain any formatting e.g.: ordered or unordered lists,
 request or response examples, links, text in bold or italic, etc.

## FIELDS

### name

The description for "name" field.
May contain any formatting e.g.: ordered or unordered lists,
 request or response examples, links, text in bold or italic, etc.

#### get

The description for "name" field for "get" action.
May contain any formatting e.g.: ordered or unordered lists,
 request or response examples, links, text in bold or italic, etc.

#### create, update

The description for "name" field for "create" and "update" actions.
May contain any formatting e.g.: ordered or unordered lists,
 request or response examples, links, text in bold or italic, etc.

## FILTERS

### name

The description for a filter by "name" field.
The formatting is not allowed here.

## SUBRESOURCES

### contacts

#### get_subresource

The documentation for a sub-resource, in this example for "get_subresource" action for "contacts" sub-resource.
May contain any formatting e.g.: ordered or unordered lists,
 request or response examples, links, text in bold or italic, etc.

The {@inheritdoc} placeholder can be used to get common documentation for an action or a field. This placeholder works only for ACTIONS and FIELDS sections.

An example:

# Acme\Bundle\AcmeBundle\Entity\AcmeEntity

## ACTIONS

### create

Create a new acme entity record.
The created record is returned in the response.

{@inheritdoc}

## FIELDS

### name

#### create

{@inheritdoc}

**The required field**

The {@request} tag can be used to add documentation depends on the request type. The full signature of this tag is {@request:expression}some text{@/request}. The expression can contain the following operators:

  • & – logical AND
  • | – logical OR
  • ! – logical NOT

For example if it is required to add text for JSON API request type, but only if it is not REST API request, the following expression can be used: json_api&!rest.

An example:

# Acme\Bundle\AcmeBundle\Entity\AcmeEntity

## ACTIONS

### create

Create a new acme entity record.
The created record is returned in the response.

{@inheritdoc}

{@request:json_api}
Example:

`</api/entities>`

` ` `JSON
{
    "data": {
       "type": "entities",
       "attributes": {
          "name": "Test Entity"
       }
    }
}
` ` `
{@/request}

## FIELDS

### name

#### create

{@inheritdoc}

**The required field**
ForumsForums
Back to top