7.3 KiB
Describes the format for specifying examples for request and response of an operation in a swagger spec. It is a dictionary of different variations of the examples for a given operation.
Why "x-ms-examples"?
We looked at the current mechanism/format provided by swagger specification to provide examples.
- For a response, swagger specification says:
| Field Pattern | Type | Description |
|---|---|---|
| {mime type} | Any | The name of the property MUST be one of the Operation produces values (either implicit or inherited). The value SHOULD be an example of what such a response would look like. |
Illustration:
{
"application/json": {
"name": "Puma",
"type": "Dog",
"color": "Black",
"gender": "Female",
"breed": "Mixed"
}
}
shortcomings/concerns: What if the service team wants to show different examples. Scenario: GET on NetworkInterface with $expand and without $expand will have an impact on the NetworkSecurityGroup property of the NIC. In the former it will be a full blown NSG and in the latter it will be a Subresource(object with one property 'id')?
- For any model definition (body parameter is a model definition; example: StorageAccountCreateParameters), swagger specification says:
| Field Name | Type | Description |
|---|---|---|
| example | Any | A free-form property to include an example of an instance for this schema. |
shortcomings/concerns: Well this is good. But it does not provide a holistic picture of the entire request/response. We have to do extra processing to join the dots. When a Service developer thinks about an API endpoint, he/she would think in terms of sending a request to the endpoint and receiving a response from that endpoint.
Hence, having an extension at every operation level in a spec, would give us the biggest bang for the buck.
Benefits of "x-ms-examples" extension:
- This will provide enough information about making a request against an endpoint/API.
- One can provide multiple examples for an operation and all of them are captured at one place.
- The sample data (provided by the service developer) in the extension will be used to validate the data models (as a part of the Travis CI while the PR is sent to the azure-rest-apis-specs repo).
- It forms the basis of better documentation. The doc team will leverage this in lightening up the REST API documentation.
- It will also be used to test the API/endpoint by running a live request with the help of some custom tool.
Where do the examples live?
We would not like to pollute the swagger spec with sample data. Hence the extension will contain a reference to the sample (a json file) in an adjacent folder (examples) of the spec.
The detailed example MUST be specified in a separate json file in the example folder under the api-version folder.
For example: The location of a swagger spec for a given service in this repo looks like this:
- azure-rest-api-specs/arm-<serviceName>/2016-01-01/swagger/<serviceName>.json. So the examples for that api-version can reside at
- azure-rest-api-specs/arm-<serviceName>/2016-01-01/examples/createFooResource.json
This will keep the spec cleaner and easy to manage.
Where can the extension be applied in the swagger spec?
Parent element: Operation Object. It is applied on the operation in the swagger spec.
Structure of the extension
- How the extension would look in the swagger spec?
- JSON schema for the extension can be found here.
{
"info": { ... },
"paths": {
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}": {
"put": {
"operationId": "StorageAccounts_CreateOrUpdate",
"description": "Creates or updates a storage account.",
"x-ms-examples": {
"Create a storage account": { "$ref": "./examples/createStorageAccount.json" },
"Update a storage account": { "$ref": "./examples/updateStorageAccount.json" }
},
"parameters": [ ... ],
"responses": { ... }
}
}
},
"definitions": { ... }
}
- Skeleton/Schema of the example provided in an individual example (json) file
- The JSON schema for the content to be provided in the example file can be found here.
"x-ms-examples": {
"example-name": { //Name of the example/scenario. It is free-form text and should succinctly describe the scenario.
"parameters": { //Provide examples for all the path, query, header, body, formData parameters as applicable.
...
},
"responses": { //Provide examples of the response headers and body per status code (as per the operation defined in the swagger spec) as applicable.
"statusCode1": {
"headers": { ... }, //Examples for location, azure-asyncoperation, retry-after response headers for long running (asynchronous) operations would be valuable
"body": { ... }
},
"statuscode2": { ... }
}
}
}
- How would the content of an example file look like?
{
"parameters": {
"subscriptionId": "34adfa4f-cedf-4dc0-ba29-b6d1a69ab345",
"resourceGroupName": "testrg123",
"storageAccountName": "testacc6141",
"api-version": "2016-01-01",
"accountCreateParameters": {
"sku": {
"name": 'Standard_LRS'
},
"kind": 'Storage',
"location": 'eastasia',
"properties": {
"encryption": {
"services": {
"blob": {
"enabled": true
}
},
"keySource": 'Microsoft.Storage'
}
}
}
},
"responses": {
"200": {
"headers": {
},
"body": {
"id": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.Storage/storageAccounts/testacc6141",
"kind": "Storage",
"location": "eastasia",
"name": "testacc6141",
"properties": {
"creationTime": "2016-04-12T19:20:33.2288820Z",
"encryption": {
"keySource": "Microsoft.Storage",
"services": {
"blob": {
"enabled": true,
"lastEnabledTime": "2016-04-12T19:20:33.2298823Z"
}
}
},
"primaryEndpoints": {
"blob": "https://testacc6141.blob.core.windows.net/",
"file": "https://testacc6141.file.core.windows.net/",
"queue": "https://testacc6141.queue.core.windows.net/",
"table": "https://testacc6141.table.core.windows.net/"
},
"primaryLocation": "eastasia",
"provisioningState": "Succeeded",
"statusOfPrimary": "Available"
},
"sku": {
"name": "Standard_LRS",
"tier": "Standard"
},
"tags": {},
"type": "Microsoft.Storage/storageAccounts"
}
}
}
}