The Documentation section is used to edit the project's documentation available for clients in the Developer portal. Most of the documentation is automatically generated based on policy definitions as well as any conversions across the proxy pipeline. Users can add further information about the business side of the resources and their applicability.
Figure 1: Documentation section properties
Below are the basic attributes present under Documentation section.
| Attribute | Description |
|---|---|
| Project Base Path | Proxy Context Path provided while creating the project. |
| Version | Version number provided while creating the project. |
| Status | Status (Active/Deprecated/Retired) of the project, as provided in the Summary section. |
| Short Description | Provide a short description of the project. |
| Long Description | Provide a detailed description of the project. If the description exceeds the text field, click more to expand the text field and view the entire data without scrolling. |
The documentation corresponding to a particular resource can be configured by selecting the resource and configuring its documentation which is classified into following sections.
- Details
- Parameters
- Custom Parameters
Details
This section comprises of optional data input fields where more details about the resource can be added to be displayed in the Developer portal.
| Attribute | Description |
|---|---|
| Short Description | Provide a short description of the resource. |
| Long Description | Provide a detailed description of the resource. If the description exceeds the text field, click more to expand the text field and view the entire data without scrolling. |
| Consumes | Provide the incoming request type. This generally corresponds to the Content-Type header of the incoming request from the client. |
| Produces | Provide the output response type after calling the target API. This generally corresponds to Accept header of the incoming request from the client. |
| Input Description | Provide details about the input to the resource. |
| Output Description | Provide details about the output from the resource |
| Input Sample | Provide a sample of the input request. This can be very helpful for developers using the API. |
| Output Sample | Provide a sample of the output response. This can be very helpful for developers using the API. |
Figure 2: Details section under Documentation
Parameters
Different parameters that are part of the invocation of the resource are automatically generated and relevant documentation is generated.
| Attribute | Description |
|---|---|
| Name | Name of the parameter. |
| Type | Type of the parameter (Form Param / Header / Query Param). |
| Default Value | Default value of this parameter. |
| Description | Details of this parameter. |
| Is Required | Whether the parameter is mandatory or optional. |
Figure 3: Parameters section under Documentation
Custom Parameters
Parameters which are not automatically generated but may be required for the target server or any service call out can be added using this section. Add parameters by clicking the Add button to add more parameters.
Type-in the parameters in the respective text fields and select from the drop-downs below.
Type: Select from the options as below
- Form Param
- Header
- Query Param
Is Required: select from the options true/false
Figure 4: Customer Parameters section under Documentation