Conversation
Change summary tags to description tags. Add proper text to reponse code descriptions Add examples for responses.
Apply better grammar.
Make the description clearer and mark the id as required
linter caught missing description
|
Hi @BrianBlum, I'm your friendly neighborhood Azure Pull Request Bot (You can call me AZPRBOT). Thanks for your contribution!
TTYL, AZPRBOT; |
| { | ||
| "nameAvailable": true, | ||
| "reason": null, | ||
| "message": null |
There was a problem hiding this comment.
Representing null values in the response provides wrong information. Swagger spec says that the properties are not required. That means they may or may not be sent in the response. Sending a null value means a different thing. So please remove them from here.
If the service is actually sending this on the wire then the service should fix it. I would recommend using fiddler to provide examples.
| "schema": { | ||
| "$ref": "#/definitions/CheckNameAvailabilityOutput" | ||
| }, | ||
| "examples": { |
There was a problem hiding this comment.
This is an incorrect format. The example in the responses section should be keyed on the MIME type.
Take a look at what the specification says https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#exampleObject
| "description": "Name of the resource group within the Azure subscription.", | ||
| "in": "path", | ||
| "required": true, | ||
| "type": "string" |
There was a problem hiding this comment.
"x-ms-parameter-location": "method"
| "type": "string", | ||
| "pattern": "^[a-z0-9]", | ||
| "minLength": 3, | ||
| "maxLength": 24 |
There was a problem hiding this comment.
"x-ms-parameter-location": "method"
| "properties": { | ||
| "apiEndpoints": { | ||
| "description": "The Media Services REST API endpoints for this resource.", | ||
| "description": "Read-only property that lists the Media Services REST API endpoints for this resource. If supplied on a PUT or PATCH, the value will be ignored.", |
There was a problem hiding this comment.
documentation says that it is readOnly. However the schema definition doesn't.
"readOnly": true
| "$ref": "#/definitions/MediaService" | ||
| }, | ||
| "examples" : { | ||
| "id": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.Media/mediaServices/{name}", |
| "$ref": "#/definitions/RegenerateKeyOutput" | ||
| }, | ||
| "examples": { | ||
| "key": "{key}" |
| "$ref": "#/definitions/ServiceKeys" | ||
| }, | ||
| "examples":{ | ||
| "primaryAuthEndpoint": "{primary-auth-endpoint}", |
There was a problem hiding this comment.
same as above. Make sure to cover all the review comments made in the first example
| "definitions": { | ||
| "ApiEndpoint": { | ||
| "description": "The properties for a Media Services REST API endpoint.", | ||
| "readOnly": true, |
There was a problem hiding this comment.
ReadOnlyness can only be applied on a model Property. It cannot be applied on the entire model. Please specify this explicicitly on every property if that is the case.
| } | ||
| }, | ||
| "definitions": { | ||
| "ApiEndpoint": { |
There was a problem hiding this comment.
why have you not provided examples for model definitions?
As per the specification (once the page loads, please scroll up a little).
example | Any | A free-form property to include an example of an instance for this schema.
|
Submitting new PR. |
…toragecache-2019-06-01-preview fix typo in databox json
3 participants
Documentation update and proper required parameter settings.
This change is