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

Features available in Outbound models

  • Dynamic Component Dependency Annotation @DynamicComponentDependency is now supported in .outbound models. Therefore if an outbound method is using a fragment that belongs to another component, then that outbound method has to be annotated with this annotation.
  • Dependency error hints are now produced in Developer Studio editor. Failing to address these dependency errors causes build errors, if that component is disabled in any of the solution-set files.
  • Generating the outbound model now generates .obd file instead of .svc file. The generated .obd file contains metadata written in blocks of 2450 characters instead of 500 characters. This reduces the number of CLOB concatenations and improves deployment performance.
  • Outbound Message Viewer: Database_SYS.Remove_Outbound method is now available to remove metadata of previously created and later on obsoleted outbound models. Database_SYS.Remove_Inactive_Metadata_ now cleans up outbound metadata as well, when a previously active component is inactivated.