Adding Examples for REST APIs
In APIM 3.0.0 onwards, the format of defining REST API examples is changed. Instead of using inline samples using x-wso2-request, x-wso2-response elements, the examples are decomposed from the main swagger and added as separate files. The files are linked to the OpenAPI definition with x-examples extension with the relative path of the example files.
The approach has below advantages:
- Avoid making the REST API definition unnecessarily longer due to examples.
- Supporting multiple examples per operation.
- Reuse examples in the test cases (for mocking API calls).
- title: [ title of the 1st example ]
id: [ id of the 1st example.]
request:
method: [ request method ]
url: [ request url ]
headers: |
[ request headers ]
response:
status:
code: [ response status code ]
msg: [ response status message ]
headers: |
[ response headers ]
body:
[ response body ]
- title: [ title of the 2nd example ]
id: [ id of the 2nd example.]
request:
method: ...
url: ...
headers: |
...
response:
...
Note:
- Every example is an array item. Note the starting
-. -
headerselement is a multiline string. Not an array. - Use a unique
idto represent the example. It needs to be unique with the examples defined in the same file.idcan be used to retrieve the example when writing React unit tests. For more information see: Mocking REST APIs for React Unit Tests
Publisher:
carbon-apimgt/components/apimgt/org.wso2.carbon.apimgt.rest.api.publisher.v1/src/main/resources/docs/examples
Store:
carbon-apimgt/components/apimgt/org.wso2.carbon.apimgt.rest.api.store.v1/src/main/resources/docs/examples
Let's say you need to add a sample for GET /apis request.
- Create the example file
Add a file (with a folder if necessary) to include the examples.
Eg: apis/apis_get.yaml
- title: Get All APIs
id: getAllAPIsSimple
request:
method: GET
url: https://localhost:9443/api/am/publisher/v1.0/apis
headers: |
Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8
response:
status:
code: 200
msg: OK
headers: |
Content-Type: application/json
body:
{
"count": 1,
"list": [
{
"id": "ae4eae22-3f65-387b-2323-d37eaa366fa8",
"name": "CalculatorAPI",
"description": "A calculator API that supports basic operations",
"context": "CalculatorAPI",
"version": "1.0.0",
"provider": "admin",
"lifeCycleStatus": "CREATED",
"workflowStatus": "APPROVED",
"hasThumbnail": true,
"securityScheme": [
"oauth2"
]
}
],
"pagination": {
"offset": 0,
"limit": 1,
"total": 1,
"next": "",
"previous": ""
}
}
- Link the sample to the OpenAPI definition
Use the relative path of the example file with x-examples extension.
x-examples:
$ref: docs/examples/apis/apis_get.yaml
- Build the REST API component to generate documentation
Do an mvn clean install in the REST API component. This will generate documentation in the docs folder in the carbon-apimgt root location with the new example you added.
There are some cases that we cannot add requests and responses in the structured format. For example, let's say you need to add examples for an API which does a multipart/form-data request. In such cases, we can add examples in raw format using rawRequest and rawResponse fields. Also, make sure add curl element with a sample request.
Note: In the earlier case, we did not add the curl element as the curl can be automatically generated from the structured request element. But we can always add a curl element there too if we need to override it. Those generated fields are available in the generated REST API documentation.
- title: Using a Valid OpenAPI Definition
rawRequest: |
POST https://localhost:9443/api/am/publisher/v1.0/apis/validate-openapi?returnContent=true HTTP/1.1
Content-Type: multipart/form-data; boundary="----=_Part_0_771605626.1563876237955"
Authorization: Bearer 031cf7d6-4f49-3089-a164-5289b171203a
Content-Length: 1504
------=_Part_0_771605626.1563876237955
Content-Type: application/octet-stream; name=swagger2-sample.1.0.0.yaml
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="file"; filename="swagger2-sample.1.0.0.yaml"
paths:
/menu:
patch:
x-auth-type: "Application & Application User"
responses:
200:
description: "OK"
x-throttling-tier: "Unlimited"
post:
x-auth-type: "Application & Application User"
responses:
200:
description: "OK"
x-throttling-tier: "Unlimited"
get:
x-auth-type: "Application & Application User"
responses:
200:
description: "OK"
x-throttling-tier: "Unlimited"
delete:
x-auth-type: "Application & Application User"
responses:
200:
description: "OK"
x-throttling-tier: "Unlimited"
put:
x-auth-type: "Application & Application User"
responses:
200:
description: "OK"
x-throttling-tier: "Unlimited"
securityDefinitions:
default:
tokenUrl: "https://test.com"
type: "oauth2"
flow: "password"
swagger: "2.0"
x-wso2-security:
apim:
x-wso2-scopes: []
info:
title: "sample"
version: "1.0.0"
------=_Part_0_771605626.1563876237955--
curl: |
curl -k -H "Authorization: Bearer 031cf7d6-4f49-3089-a164-5289b171203a" -F [email protected] -X POST https://localhost:9443/api/am/publisher/v1.0/apis/validate-openapi?returnContent=true
rawResponse: |
HTTP/1.1 200 OK
Date: Tue, 23 Jul 2019 10:04:01 GMT
Content-Type: application/json
Transfer-Encoding: chunked
{
"isValid" : true,
"content" : " paths: \n /menu: \n patch: \n x-auth-type: \"Application & Application User\"\n responses: \n 200: \n description: \"OK\"\n x-throttling-tier: \"Unlimited\"\n post: \n x-auth-type: \"Application & Application User\"\n responses: \n 200: \n description: \"OK\"\n x-throttling-tier: \"Unlimited\"\n get: \n x-auth-type: \"Application & Application User\"\n responses: \n 200: \n description: \"OK\"\n x-throttling-tier: \"Unlimited\"\n delete: \n x-auth-type: \"Application & Application User\"\n responses: \n 200: \n description: \"OK\"\n x-throttling-tier: \"Unlimited\"\n put: \n x-auth-type: \"Application & Application User\"\n responses: \n 200: \n description: \"OK\"\n x-throttling-tier: \"Unlimited\"\n securityDefinitions: \n default: \n tokenUrl: \"https://test.com\"\n type: \"oauth2\"\n flow: \"password\"\n swagger: \"2.0\"\n x-wso2-security: \n apim: \n x-wso2-scopes: []\n info: \n title: \"sample\"\n version: \"1.0.0\"\n",
"errors" : [ ]
}