How-To: Generating Documentation for RAD Server APIs

RAD Studio allows you to create API documentation for new RAD Server Resource modules in YAML and JSON format. The new implementation is based in the Swagger RESTful API Documentation Specification.

EMS.ResourceType implements the new attributes that can be used to generate API documentation for the EndPoints of a Resource.

EndPointRequestSummary

Description of a method:

• Tags: Defines a tag.
• Summary: A method title.
• Description: A method description.
• Produces: A MIME type that the API can produce. This is global to all APIs but can be overridden on specific API calls. The value must be as described under Mime Types.
• Consume: A MIME type that the API can consume. This is global to all APIs but can be overridden on specific API calls. The value must be as described under Mime Types.

Example of description declaration of a GET method of an EndPoint:

EndPointRequestParameter

Description of the parameters used in a request.

A unique parameter is defined by a combination of a name and location.

There are five possible parameter types: Path, Query, Header, Body, and Form.

• ParamIn: The location of the parameter: Path, Query, Header, Body or Form.
• Name: The name of the parameter. Parameter names are case sensitive.
  • When the location of the parameter is ‘Body’, the name must be ‘body’.
  • When the location of the parameter is ‘Path’, the name must correspond to the associated path segment from the path field in the Paths object.
  • For the rest of cases, the name corresponds with ParamIn.
• Description: A brief description of the parameter. This could contain examples of use. GFM syntax can be used for rich text representation.
• Required: Determines if this parameter is mandatory. If the parameter is in ‘Path’, this property is required and its value must be True, otherwise the property may be included and its default value is False.
• ParamType: The type of the parameter. For other value than ‘Body’, the value must be one of the following values: ‘spArray’, ‘spBoolean’, ‘spInteger’, ‘spNumber’, ‘spNull’, ‘spObject’, ‘spString’, ‘spFile’. If ParamType is ‘spFile’, the consume MIME type must be either “multipart/form-data” or “application/x-www-form-urlencoded”, and the parameter must be in “form-data”. For the value ‘Body’, JSONSchema and Reference are required.
• ItemFormat: The extending format for the ParamType: ‘None’, ‘Int32’, ‘Int64’, ‘Float’, ‘Double’, ‘Byte’, ‘Date’, ‘DateTime’, ‘Password’.
• ItemType: Required if ParamType is ‘array’. It describes the type of items in the array.
• JSONSchema: The Schema Definition of the Primitive sent to the server. A definition of the body request structure. If ParamType is ‘Array’ or ‘Object’, a schema can be defined.
  • For example:

    In JSON format: {“type”: “object”,”additionalProperties”: {“type”: “string”}}.

    In YAML format:

     

    type: object

    additionalProperties:

    type: string

• Reference: The Schema Definition of the Primitive sent to the server. A definition of the body request structure. If Type is ‘Array’ or ‘Object’, a schema can be defined.
  • For example:

    ‘#/definitions/pet’

EndPointResponseDetails

Description of the request responses:

• Code: The response code.
• Description: Description of the response code.
• PrimitiveType: The Type of the Primitive returned. Primitive data types in the Swagger Specification are based on the types supported by the JSON-Schema Draft 4. JSON Schema defines seven primitive types for JSON values: ‘spArray’, ‘spBoolean’, ‘spInteger’, ‘spNumber’, ‘spNull’, ‘spObject’, ‘spString’. See JSON Schema primitive types. An additional primitive data type, ‘spFile’, is used by the Parameter Object and the Response Object to set the parameter type or the response as being a file.
• PrimitiveFormat: The Format of the Primitive returned, for example: ‘None’, ‘Int32’, ‘Int64’, ‘Float’, ‘Double’, ‘Byte’, ‘Date’, ‘DateTime’, ‘Password’.
• Schema:
  • For example:

    In JSON format: {“type”: “object”,”additionalProperties”: {“type”: “string”}}.

    in YAML format:

     

    type: object

    additionalProperties:

    type: string

• Reference: The Schema Definition of the Primitive returned. A definition of the response structure. If PrimitiveType is ‘spArray’ or ‘spObject’, a Schema definition can be defined:
  • For example:

    ‘#/definitions/pet’

EndPointObjectsYAMLDefinitions

Definition of objects for the API YAML version.

• Objects: YAML Objects definitions.

EndPointObjectsJSONDefinitions

Definition of objects for the API JSON version.

• Objects: JSON Objects definitions.