Skip to content

Marble Support for API Documentation

Marble Support for API Documentation is supported in Developer Studio for Projection models. There are set of new syntaxes available in the form of annotations. Those syntaxes allow developers to manually document RESTful APIs.

Sections that can be documented

  • Projection
  • Entities
  • Entity Sets
  • Functions
  • Actions
  • Queries
  • Summaries
  • Structures

Documentation Template Generation

A template for the documentation to be written can be generated from Developer Studio.

Developers can click on the element name and a bulb will be displayed in the left side gutter. Once it is clicked, there will be an option named Generate API Documentation which will generate a documentation stub.

Available Syntaxes

There are several syntaxes available in the form of annotations.

  • @apidoc { }
    Indicates the starting point of the API documentation block.

  • @description:
    Short and meaningful description about the element.

  • @param ParamName:
    Short and meaningful documentation about the parameters.
    Applicable for Functions, Actions.

  • @attribute AttributeName:
    Short and meaningful description about the attribute.
    Applicable for Entities, EntitySets, Structures, Queries and Summaries.

  • @return:
    Description about the return type.

  • @navigation:
    Description about the navigation.

  • << >>
    Multiline documentation. Markdown can be used to format the string

When generating code for the model file, a separate file is generated with the suffix DocMetaData.json and will contain the documentation written in the model.
The API Explorer will pick the written document and display in a swagger format.

Outbound Modeling

A new model type called outbound is introduced to support the documentation of OUTBOUND APIs. With the replacement of BizAPIs, there was a need to support documentation of OUTBOUND BizAPIs as the Interface Browser became obsolete.

To add in-source documentation to the outbound services, you need to create an Outbound model, it is same as creating other models. This model type describes all exposed services and it's payload.

Top level elements:

Element Description
Method Describes an outbound services and it's connected payload

Method attributes:

Attribute Description
PayloadCreationMethod Specifies the API method to create the payload, i.e. "Demo_Sales_API.Create_Payload"
Structure Reference to the structure datasource specified in a fragment, i.e. DemoSalesFragment.DemoSalesStruct
DataType Which format the result will end up in, json or xml

Known limitations of Outbound models in 21R2

  • Dynamic Component Dependency annotation "@DynamicComponentDependency " is not yet supported in .outbound models. Therefore if an outbound method is using a fragment that belongs to another component, the developer must make sure the correct dynamic dependency is available in respective deploy.ini file. If not there will be build errors if that component is disabled in any of the solution-set files.

  • Dependency Hints support is not available for .outbound models in Developer Studio for 21R2. This means that dependency error hints are not produced in Developer Studio editor for .outbound models. Developers should be mindful about having dynamic dependencies to other components in absence of this functionality.