From dc99beda43157a41e996edf74ed46b17726b5946 Mon Sep 17 00:00:00 2001 From: Mike Budzynski Date: Wed, 14 Apr 2021 15:08:48 -0700 Subject: [PATCH 1/4] APIM: improve the documentation for dev portal operations --- .../2021-01-01-preview/apimcontenttypes.json | 44 ++++++--- .../apimportalrevisions.json | 18 ++-- .../2021-01-01-preview/definitions.json | 94 +++++++++---------- .../stable/2020-12-01/apimcontenttypes.json | 44 ++++++--- .../2020-12-01/apimportalrevisions.json | 18 ++-- 5 files changed, 123 insertions(+), 95 deletions(-) diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json index 70b1f5dbff50..d8fab6d996b0 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json @@ -40,7 +40,7 @@ "ContentType" ], "operationId": "ContentType_ListByService", - "description": "Returns list of content types", + "description": "Lists the developer portal's content types. Content types describe content items' properties, validation rules, and constraints.", "x-ms-examples": { "ApiManagementListContentTypes": { "$ref": "./examples/ApiManagementListContentTypes.json" @@ -62,7 +62,7 @@ ], "responses": { "200": { - "description": "Lists a collection of content type entities.", + "description": "Returns a collection of the Content Type entities.", "schema": { "$ref": "./definitions.json#/definitions/ContentTypeCollection" } @@ -85,7 +85,7 @@ "ContentType" ], "operationId": "ContentType_Get", - "description": "Gets API Management content type details.", + "description": "Gets the details of the developer portal's content type. Content types describe content items' properties, validation rules, and constraints.", "x-ms-examples": { "ApiManagementGetContentType": { "$ref": "./examples/ApiManagementGetContentType.json" @@ -110,7 +110,7 @@ ], "responses": { "200": { - "description": "Get the details of the content type.", + "description": "Returns the details of the specified content type.", "schema": { "$ref": "./definitions.json#/definitions/ContentTypeContract" }, @@ -134,7 +134,7 @@ "ContentType" ], "operationId": "ContentType_CreateOrUpdate", - "description": "Creates or updates an Content Type.", + "description": "Creates or updates the developer portal's content type. Content types describe content items' properties, validation rules, and constraints. Custom content types' identifiers need to start with the `c-` prefix. Built-in content types can't be modified.", "x-ms-examples": { "ApiManagementCreateContentType": { "$ref": "./examples/ApiManagementCreateContentType.json" @@ -162,7 +162,7 @@ ], "responses": { "201": { - "description": "Content type was successfully created.", + "description": "The content type was successfully created.", "headers": { "ETag": { "description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.", @@ -198,7 +198,7 @@ "ContentType" ], "operationId": "ContentType_Delete", - "description": "Removes specified content type.", + "description": "Removes the specified developer portal's content type. Content types describe content items' properties, validation rules, and constraints. Built-in content types (with identifiers starting with the `c-` prefix) can't be removed.", "x-ms-examples": { "ApiManagementDeleteContentType": { "$ref": "./examples/ApiManagementDeleteContentType.json" @@ -246,7 +246,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_ListByService", - "description": "Returns list of content items", + "description": "Lists developer portal's content items specified by the provided content type.", "x-ms-examples": { "ApiManagementListContentTypeContentItems": { "$ref": "./examples/ApiManagementListContentTypeContentItems.json" @@ -267,11 +267,25 @@ }, { "$ref": "./apimanagement.json#/parameters/SubscriptionIdParameter" + }, + { + "name": "$filter", + "in": "query", + "required": false, + "type": "string", + "description": "Filters the results based on the provided query. Supported functions: `contains`, `startswith`, `endswith`, `eq`. Supported fields: any field from the properties object. For example, `$filter=contains(title,'test')`." + }, + { + "name": "$orderby", + "in": "query", + "required": false, + "type": "string", + "description": "Sorts the results by the provided property. Supported options: `asc`, `desc`. Supported fields: any field from the properties object. For example, `$orderby=en_us/title desc`." } ], "responses": { "200": { - "description": "Lists a collection of Content Type entities.", + "description": "Returns a collection of Content Type entities.", "schema": { "$ref": "./definitions.json#/definitions/ContentItemCollection" } @@ -294,7 +308,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_GetEntityTag", - "description": "Returns content item metadata", + "description": "Returns the entity state (ETag) version of the developer portal's content item specified by its identifier.", "x-ms-examples": { "ApiManagementHeadContentTypeContentItem": { "$ref": "./examples/ApiManagementHeadContentTypeContentItem.json" @@ -343,7 +357,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_Get", - "description": "Returns content item details", + "description": "Returns the developer portal's content item specified by its identifier.", "x-ms-examples": { "ApiManagementGetContentTypeContentItem": { "$ref": "./examples/ApiManagementGetContentTypeContentItem.json" @@ -371,7 +385,7 @@ ], "responses": { "200": { - "description": "Get the details of the content item.", + "description": "Returns the Content Item entity.", "schema": { "$ref": "./definitions.json#/definitions/ContentItemContract" }, @@ -395,7 +409,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_CreateOrUpdate", - "description": "Creates new content item", + "description": "Creates a new developer portal's content item specified by the provided content type.", "x-ms-examples": { "ApiManagementCreateContentTypeContentItem": { "$ref": "./examples/ApiManagementCreateContentTypeContentItem.json" @@ -426,7 +440,7 @@ ], "responses": { "201": { - "description": "Content item was successfully created.", + "description": "The content item was successfully created.", "headers": { "ETag": { "description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.", @@ -462,7 +476,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_Delete", - "description": "Removes specified content item.", + "description": "Removes the specified developer portal's content item.", "x-ms-examples": { "ApiManagementDeleteContentTypeContentItem": { "$ref": "./examples/ApiManagementDeleteContentTypeContentItem.json" diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimportalrevisions.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimportalrevisions.json index 6a1d3ea6cfba..ac068add6e74 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimportalrevisions.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimportalrevisions.json @@ -40,7 +40,7 @@ "PortalRevision" ], "operationId": "PortalRevision_ListByService", - "description": "Lists a collection of developer portal revision entities.", + "description": "Lists developer portal's revisions.", "x-ms-examples": { "ApiManagementListPortalRevisions": { "$ref": "./examples/ApiManagementListPortalRevisions.json" @@ -75,7 +75,7 @@ ], "responses": { "200": { - "description": "Lists a collection of developer portal revision entities.", + "description": "Returns a collection of Portal Revision entities.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionCollection" } @@ -98,7 +98,7 @@ "PortalRevision" ], "operationId": "PortalRevision_GetEntityTag", - "description": "Gets developer portal revision specified by its identifier.", + "description": "Gets the developer portal revision specified by its identifier.", "x-ms-examples": { "ApiManagementHeadPortalRevision": { "$ref": "./examples/ApiManagementHeadPortalRevision.json" @@ -123,7 +123,7 @@ ], "responses": { "200": { - "description": "Specified Portal revision entity exists and current entity state version is present in the ETag header.", + "description": "The specified portal revision entity exists and current entity state version is present in the ETag header.", "headers": { "ETag": { "description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.", @@ -144,7 +144,7 @@ "PortalRevision" ], "operationId": "PortalRevision_Get", - "description": "Gets developer portal revision specified by its identifier.", + "description": "Gets the developer portal's revision specified by its identifier.", "x-ms-examples": { "ApiManagementGetPortalRevision": { "$ref": "./examples/ApiManagementGetPortalRevision.json" @@ -169,7 +169,7 @@ ], "responses": { "200": { - "description": "Gets the specified developer portal revision entity.", + "description": "Gets the specified Portal Revision entity.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionContract" }, @@ -193,7 +193,7 @@ "PortalRevision" ], "operationId": "PortalRevision_CreateOrUpdate", - "description": "Creates a new developer portal revision.", + "description": "Creates a new developer portal's revision by running the portal's publishing. The `isCurrent` property indicates if the revision is publicly accessible.", "x-ms-examples": { "ApiManagementCreatePortalRevision": { "$ref": "./examples/ApiManagementCreatePortalRevision.json" @@ -226,10 +226,10 @@ ], "responses": { "202": { - "description": "Request to create developer portal revision was accepted." + "description": "Request to create a developer portal revision was accepted." }, "201": { - "description": "Developer portal revision was successfully created.", + "description": "The developer portal revision was successfully created.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionContract" }, diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/definitions.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/definitions.json index 216fe4a2983a..3f3c7a610a77 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/definitions.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/definitions.json @@ -231,14 +231,14 @@ "readOnly": true } }, - "description": "Paged Api list representation." + "description": "Paged API list representation." }, "ApiContract": { "properties": { "properties": { "x-ms-client-flatten": true, "$ref": "#/definitions/ApiContractProperties", - "description": "Api entity contract properties." + "description": "API entity contract properties." } }, "allOf": [ @@ -246,7 +246,7 @@ "$ref": "./apimanagement.json#/definitions/Resource" } ], - "description": "Api details." + "description": "API details." }, "ApiContractProperties": { "properties": { @@ -302,14 +302,14 @@ "required": [ "path" ], - "description": "Api Entity Properties" + "description": "API Entity Properties" }, "ApiCreateOrUpdateParameter": { "properties": { "properties": { "x-ms-client-flatten": true, "$ref": "#/definitions/ApiCreateOrUpdateProperties", - "description": "Api entity create of update properties." + "description": "API entity create of update properties." } }, "description": "API Create or Update Parameters." @@ -398,7 +398,7 @@ }, "apiType": { "type": "string", - "description": "Type of Api to create. \n * `http` creates a REST API \n * `soap` creates a SOAP pass-through API \n * `websocket` creates websocket API.", + "description": "Type of API to create. \n * `http` creates a REST API \n * `soap` creates a SOAP pass-through API \n * `websocket` creates websocket API.", "enum": [ "http", "soap", @@ -433,7 +433,7 @@ "$ref": "#/definitions/ApiContractProperties" } ], - "description": "Api Create or Update Properties." + "description": "API Create or Update Properties." }, "ApiEntityBaseContract": { "properties": { @@ -465,13 +465,13 @@ }, "apiRevision": { "type": "string", - "description": "Describes the Revision of the Api. If no value is provided, default revision 1 is created", + "description": "Describes the revision of the API. If no value is provided, default revision 1 is created", "minLength": 1, "maxLength": 100 }, "apiVersion": { "type": "string", - "description": "Indicates the Version identifier of the API if the API is versioned", + "description": "Indicates the version identifier of the API if the API is versioned", "maxLength": 100 }, "isCurrent": { @@ -485,12 +485,12 @@ }, "apiRevisionDescription": { "type": "string", - "description": "Description of the Api Revision.", + "description": "Description of the API Revision.", "maxLength": 256 }, "apiVersionDescription": { "type": "string", - "description": "Description of the Api Version.", + "description": "Description of the API Version.", "maxLength": 256 }, "apiVersionSetId": { @@ -569,31 +569,31 @@ "values": [ { "value": "swagger-link-json", - "description": "The Api Definition is exported in OpenApi Specification 2.0 format to the Storage Blob.", + "description": "The API Definition is exported in OpenAPI Specification 2.0 format to the Storage Blob.", "name": "Swagger" }, { "value": "wsdl-link+xml", - "description": "The Api Definition is exported in WSDL Schema to Storage Blob. This is only supported for APIs of Type `soap`", + "description": "The API Definition is exported in WSDL Schema to Storage Blob. This is only supported for APIs of Type `soap`", "name": "Wsdl" }, { "value": "wadl-link-json", - "description": "Export the Api Definition in WADL Schema to Storage Blob.", + "description": "Export the API Definition in WADL Schema to Storage Blob.", "name": "Wadl" }, { "value": "openapi-link", - "description": "Export the Api Definition in OpenApi Specification 3.0 to Storage Blob.", + "description": "Export the API Definition in OpenAPI Specification 3.0 to Storage Blob.", "name": "OpenApi" } ] }, - "description": "Format in which the Api Details are exported to the Storage Blob with Sas Key valid for 5 minutes." + "description": "Format in which the API Details are exported to the Storage Blob with Sas Key valid for 5 minutes." }, "value": { "type": "object", - "description": "The object defining the schema of the exported Api Detail", + "description": "The object defining the schema of the exported API Detail", "properties": { "link": { "type": "string", @@ -688,7 +688,7 @@ "readOnly": true } }, - "description": "Paged Api Revision list representation." + "description": "Paged API Revision list representation." }, "ApiRevisionContract": { "properties": { @@ -886,14 +886,14 @@ "description": "Next page link if any." } }, - "description": "Paged Api Version Set list representation." + "description": "Paged API Version Set list representation." }, "ApiVersionSetContract": { "properties": { "properties": { "x-ms-client-flatten": true, "$ref": "#/definitions/ApiVersionSetContractProperties", - "description": "Api VersionSet contract properties." + "description": "API VersionSet contract properties." } }, "allOf": [ @@ -901,7 +901,7 @@ "$ref": "./apimanagement.json#/definitions/Resource" } ], - "description": "Api Version Set Contract details." + "description": "API Version Set Contract details." }, "ApiVersionSetContractDetails": { "description": "An API Version Set contains the common configuration for a set of API Versions relating ", @@ -1003,17 +1003,17 @@ "maxLength": 100 } }, - "description": "Api Version set base parameters" + "description": "API Version set base parameters" }, "ApiVersionSetUpdateParameters": { "properties": { "properties": { "x-ms-client-flatten": true, "$ref": "#/definitions/ApiVersionSetUpdateParametersProperties", - "description": "Parameters to update or create an Api Version Set Contract." + "description": "Parameters to update or create an API Version Set Contract." } }, - "description": "Parameters to update or create an Api Version Set Contract." + "description": "Parameters to update or create an API Version Set Contract." }, "ApiVersionSetUpdateParametersProperties": { "properties": { @@ -1434,7 +1434,7 @@ }, "resourceId": { "type": "string", - "description": "Management Uri of the Resource in External System. This url can be the Arm Resource Id of Logic Apps, Function Apps or Api Apps.", + "description": "Management Uri of the Resource in External System. This url can be the Arm Resource Id of Logic Apps, Function Apps or API Apps.", "minLength": 1, "maxLength": 2000 }, @@ -2258,7 +2258,7 @@ }, "isDefault": { "type": "boolean", - "description": "Whether the template is the default template provided by Api Management or has been edited.", + "description": "Whether the template is the default template provided by API Management or has been edited.", "readOnly": true }, "parameters": { @@ -3020,7 +3020,7 @@ "properties": { "secretIdentifier": { "type": "string", - "description": "Key vault secret identifier for fetching secret. Providing a versioned secret will prevent auto-refresh. This requires Api Management service to be configured with aka.ms/apimmsi" + "description": "Key vault secret identifier for fetching secret. Providing a versioned secret will prevent auto-refresh. This requires API Management service to be configured with aka.ms/apimmsi" }, "identityClientId": { "type": "string", @@ -3441,7 +3441,7 @@ "$ref": "./apimanagement.json#/definitions/Resource" } ], - "description": "Api Operation details." + "description": "API Operation details." }, "OperationContractProperties": { "properties": { @@ -3508,7 +3508,7 @@ "description": "Operation Policies" } }, - "description": "Api Operation Entity Base Contract details." + "description": "API Operation Entity Base Contract details." }, "OperationResultContract": { "properties": { @@ -3589,17 +3589,17 @@ }, "apiName": { "type": "string", - "description": "Api Name.", + "description": "API Name.", "readOnly": true }, "apiRevision": { "type": "string", - "description": "Api Revision.", + "description": "API Revision.", "readOnly": true }, "apiVersion": { "type": "string", - "description": "Api Version.", + "description": "API Version.", "readOnly": true }, "description": { @@ -3632,7 +3632,7 @@ "description": "Properties of the API Operation entity that can be updated." } }, - "description": "Api Operation Update Contract details." + "description": "API Operation Update Contract details." }, "OperationUpdateContractProperties": { "properties": { @@ -4922,7 +4922,7 @@ "items": { "$ref": "#/definitions/SchemaContract" }, - "description": "Api Schema Contract value.", + "description": "API Schema Contract value.", "readOnly": true }, "count": { @@ -5441,7 +5441,7 @@ }, "api": { "$ref": "#/definitions/ApiTagResourceContractProperties", - "description": "Api associated with the tag." + "description": "API associated with the tag." }, "operation": { "$ref": "#/definitions/OperationTagResourceContractProperties", @@ -6324,19 +6324,19 @@ "readOnly": true } }, - "description": "Paged deleted Api Management Services List Representation." + "description": "Paged deleted API Management Services List Representation." }, "DeletedServiceContract": { "properties": { "properties": { "x-ms-client-flatten": true, "$ref": "#/definitions/DeletedServiceContractProperties", - "description": "Deleted Api Management Service details." + "description": "Deleted API Management Service details." }, "location": { "readOnly": true, "type": "string", - "description": "Api Management Service Master Location." + "description": "API Management Service Master Location." } }, "allOf": [ @@ -6344,7 +6344,7 @@ "$ref": "./apimanagement.json#/definitions/Resource" } ], - "description": "Deleted Api Management Service information." + "description": "Deleted API Management Service information." }, "DeletedServiceContractProperties": { "properties": { @@ -6395,7 +6395,7 @@ "$ref": "./apimanagement.json#/definitions/Resource" } ], - "description": "Portal revisions contract details." + "description": "Portal Revision's contract details." }, "PortalRevisionContractProperties": { "properties": { @@ -6412,7 +6412,7 @@ }, "status": { "type": "string", - "description": "Portal revision publishing status", + "description": "Status of the portal's revision.", "enum": [ "pending", "publishing", @@ -6425,19 +6425,19 @@ "values": [ { "value": "pending", - "description": "Portal revision publishing is pending" + "description": "Portal's revision has been queued." }, { "value": "publishing", - "description": "Portal revision is publishing" + "description": "Portal's revision is being published." }, { "value": "completed", - "description": "Portal revision publishing completed" + "description": "Portal's revision publishing completed." }, { "value": "failed", - "description": "Portal revision publishing failed" + "description": "Portal's revision publishing failed." } ] }, @@ -6445,13 +6445,13 @@ }, "isCurrent": { "type": "boolean", - "description": "Indicates if the Portal Revision is public." + "description": "Indicates if the portal's revision is public." }, "createdDateTime": { "type": "string", "readOnly": true, "format": "date-time", - "description": "Portal revision creation date and time." + "description": "Portal's revision creation date and time." }, "updatedDateTime": { "type": "string", diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json index 7e48ce96c972..4fe6afee64d3 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json @@ -40,7 +40,7 @@ "ContentType" ], "operationId": "ContentType_ListByService", - "description": "Returns list of content types", + "description": "Lists the developer portal's content types. Content types describe content items' properties, validation rules, and constraints.", "x-ms-examples": { "ApiManagementListContentTypes": { "$ref": "./examples/ApiManagementListContentTypes.json" @@ -62,7 +62,7 @@ ], "responses": { "200": { - "description": "Lists a collection of content type entities.", + "description": "Returns a collection of the Content Type entities.", "schema": { "$ref": "./definitions.json#/definitions/ContentTypeCollection" } @@ -85,7 +85,7 @@ "ContentType" ], "operationId": "ContentType_Get", - "description": "Gets API Management content type details.", + "description": "Gets the details of the developer portal's content type. Content types describe content items' properties, validation rules, and constraints.", "x-ms-examples": { "ApiManagementGetContentType": { "$ref": "./examples/ApiManagementGetContentType.json" @@ -110,7 +110,7 @@ ], "responses": { "200": { - "description": "Get the details of the content type.", + "description": "Returns the details of the specified content type.", "schema": { "$ref": "./definitions.json#/definitions/ContentTypeContract" }, @@ -134,7 +134,7 @@ "ContentType" ], "operationId": "ContentType_CreateOrUpdate", - "description": "Creates or updates an Content Type.", + "description": "Creates or updates the developer portal's content type. Content types describe content items' properties, validation rules, and constraints. Custom content types' identifiers need to start with the `c-` prefix. Built-in content types can't be modified.", "x-ms-examples": { "ApiManagementCreateContentType": { "$ref": "./examples/ApiManagementCreateContentType.json" @@ -162,7 +162,7 @@ ], "responses": { "201": { - "description": "Content type was successfully created.", + "description": "The content type was successfully created.", "headers": { "ETag": { "description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.", @@ -198,7 +198,7 @@ "ContentType" ], "operationId": "ContentType_Delete", - "description": "Removes specified content type.", + "description": "Removes the specified developer portal's content type. Content types describe content items' properties, validation rules, and constraints. Built-in content types (with identifiers starting with the `c-` prefix) can't be removed.", "x-ms-examples": { "ApiManagementDeleteContentType": { "$ref": "./examples/ApiManagementDeleteContentType.json" @@ -246,7 +246,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_ListByService", - "description": "Returns list of content items", + "description": "Lists developer portal's content items specified by the provided content type.", "x-ms-examples": { "ApiManagementListContentTypeContentItems": { "$ref": "./examples/ApiManagementListContentTypeContentItems.json" @@ -267,11 +267,25 @@ }, { "$ref": "./apimanagement.json#/parameters/SubscriptionIdParameter" + }, + { + "name": "$filter", + "in": "query", + "required": false, + "type": "string", + "description": "Filters the results based on the provided query. Supported functions: `contains`, `startswith`, `endswith`, `eq`. Supported fields: any field from the properties object. For example, `$filter=contains(title,'test')`." + }, + { + "name": "$orderby", + "in": "query", + "required": false, + "type": "string", + "description": "Sorts the results by the provided property. Supported options: `asc`, `desc`. Supported fields: any field from the properties object. For example, `$orderby=en_us/title desc`." } ], "responses": { "200": { - "description": "Lists a collection of Content Type entities.", + "description": "Returns a collection of Content Type entities.", "schema": { "$ref": "./definitions.json#/definitions/ContentItemCollection" } @@ -294,7 +308,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_GetEntityTag", - "description": "Returns content item metadata", + "description": "Returns the entity state (ETag) version of the developer portal's content item specified by its identifier.", "x-ms-examples": { "ApiManagementHeadContentTypeContentItem": { "$ref": "./examples/ApiManagementHeadContentTypeContentItem.json" @@ -343,7 +357,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_Get", - "description": "Returns content item details", + "description": "Returns the developer portal's content item specified by its identifier.", "x-ms-examples": { "ApiManagementGetContentTypeContentItem": { "$ref": "./examples/ApiManagementGetContentTypeContentItem.json" @@ -371,7 +385,7 @@ ], "responses": { "200": { - "description": "Get the details of the content item.", + "description": "Returns the Content Item entity.", "schema": { "$ref": "./definitions.json#/definitions/ContentItemContract" }, @@ -395,7 +409,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_CreateOrUpdate", - "description": "Creates new content item", + "description": "Creates a new developer portal's content item specified by the provided content type.", "x-ms-examples": { "ApiManagementCreateContentTypeContentItem": { "$ref": "./examples/ApiManagementCreateContentTypeContentItem.json" @@ -426,7 +440,7 @@ ], "responses": { "201": { - "description": "Content item was successfully created.", + "description": "The content item was successfully created.", "headers": { "ETag": { "description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.", @@ -462,7 +476,7 @@ "ContentTypeContentItem" ], "operationId": "ContentItem_Delete", - "description": "Removes specified content item.", + "description": "Removes the specified developer portal's content item.", "x-ms-examples": { "ApiManagementDeleteContentTypeContentItem": { "$ref": "./examples/ApiManagementDeleteContentTypeContentItem.json" diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimportalrevisions.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimportalrevisions.json index d9fd24b5f925..de2ecfc67143 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimportalrevisions.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimportalrevisions.json @@ -40,7 +40,7 @@ "PortalRevision" ], "operationId": "PortalRevision_ListByService", - "description": "Lists a collection of developer portal revision entities.", + "description": "Lists developer portal's revisions.", "x-ms-examples": { "ApiManagementListPortalRevisions": { "$ref": "./examples/ApiManagementListPortalRevisions.json" @@ -75,7 +75,7 @@ ], "responses": { "200": { - "description": "Lists a collection of developer portal revision entities.", + "description": "Returns a collection of Portal Revision entities.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionCollection" } @@ -98,7 +98,7 @@ "PortalRevision" ], "operationId": "PortalRevision_GetEntityTag", - "description": "Gets developer portal revision specified by its identifier.", + "description": "Gets the developer portal revision specified by its identifier.", "x-ms-examples": { "ApiManagementHeadPortalRevision": { "$ref": "./examples/ApiManagementHeadPortalRevision.json" @@ -123,7 +123,7 @@ ], "responses": { "200": { - "description": "Specified Portal revision entity exists and current entity state version is present in the ETag header.", + "description": "The specified portal revision entity exists and current entity state version is present in the ETag header.", "headers": { "ETag": { "description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.", @@ -144,7 +144,7 @@ "PortalRevision" ], "operationId": "PortalRevision_Get", - "description": "Gets developer portal revision specified by its identifier.", + "description": "Gets the developer portal's revision specified by its identifier.", "x-ms-examples": { "ApiManagementGetPortalRevision": { "$ref": "./examples/ApiManagementGetPortalRevision.json" @@ -169,7 +169,7 @@ ], "responses": { "200": { - "description": "Gets the specified developer portal revision entity.", + "description": "Gets the specified Portal Revision entity.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionContract" }, @@ -193,7 +193,7 @@ "PortalRevision" ], "operationId": "PortalRevision_CreateOrUpdate", - "description": "Creates a new developer portal revision.", + "description": "Creates a new developer portal's revision by running the portal's publishing. The `isCurrent` property indicates if the revision is publicly accessible.", "x-ms-examples": { "ApiManagementCreatePortalRevision": { "$ref": "./examples/ApiManagementCreatePortalRevision.json" @@ -226,10 +226,10 @@ ], "responses": { "202": { - "description": "Request to create developer portal revision was accepted." + "description": "Request to create a developer portal revision was accepted." }, "201": { - "description": "Developer portal revision was successfully created.", + "description": "The developer portal revision was successfully created.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionContract" }, From d702e58ef329a29aed0b8c752918441fe0aad55b Mon Sep 17 00:00:00 2001 From: Mike Budzynski Date: Wed, 14 Apr 2021 15:33:56 -0700 Subject: [PATCH 2/4] Minor changes --- .../preview/2021-01-01-preview/apimcontenttypes.json | 2 +- .../preview/2021-01-01-preview/apimportalrevisions.json | 4 ++-- .../stable/2020-12-01/apimcontenttypes.json | 2 +- .../stable/2020-12-01/apimportalrevisions.json | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json index d8fab6d996b0..6becfb2e181d 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json @@ -385,7 +385,7 @@ ], "responses": { "200": { - "description": "Returns the Content Item entity.", + "description": "Returns the content item.", "schema": { "$ref": "./definitions.json#/definitions/ContentItemContract" }, diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimportalrevisions.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimportalrevisions.json index ac068add6e74..c70f56bc6af2 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimportalrevisions.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimportalrevisions.json @@ -75,7 +75,7 @@ ], "responses": { "200": { - "description": "Returns a collection of Portal Revision entities.", + "description": "Lists portal's revisions.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionCollection" } @@ -169,7 +169,7 @@ ], "responses": { "200": { - "description": "Gets the specified Portal Revision entity.", + "description": "Gets the specified portal's revision.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionContract" }, diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json index 4fe6afee64d3..37b7d65d303d 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json @@ -385,7 +385,7 @@ ], "responses": { "200": { - "description": "Returns the Content Item entity.", + "description": "Returns the content item.", "schema": { "$ref": "./definitions.json#/definitions/ContentItemContract" }, diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimportalrevisions.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimportalrevisions.json index de2ecfc67143..613cb5a414ba 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimportalrevisions.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimportalrevisions.json @@ -75,7 +75,7 @@ ], "responses": { "200": { - "description": "Returns a collection of Portal Revision entities.", + "description": "Lists portal's revisions.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionCollection" } @@ -169,7 +169,7 @@ ], "responses": { "200": { - "description": "Gets the specified Portal Revision entity.", + "description": "Gets the specified portal's revision.", "schema": { "$ref": "./definitions.json#/definitions/PortalRevisionContract" }, From ba256da264491c51a677b68c0f6733ea4bbd7a50 Mon Sep 17 00:00:00 2001 From: Mike Budzynski Date: Wed, 14 Apr 2021 15:35:41 -0700 Subject: [PATCH 3/4] Removing OData parameters from the stable API version --- .../stable/2020-12-01/apimcontenttypes.json | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json index 37b7d65d303d..a56dc685e138 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2020-12-01/apimcontenttypes.json @@ -267,20 +267,6 @@ }, { "$ref": "./apimanagement.json#/parameters/SubscriptionIdParameter" - }, - { - "name": "$filter", - "in": "query", - "required": false, - "type": "string", - "description": "Filters the results based on the provided query. Supported functions: `contains`, `startswith`, `endswith`, `eq`. Supported fields: any field from the properties object. For example, `$filter=contains(title,'test')`." - }, - { - "name": "$orderby", - "in": "query", - "required": false, - "type": "string", - "description": "Sorts the results by the provided property. Supported options: `asc`, `desc`. Supported fields: any field from the properties object. For example, `$orderby=en_us/title desc`." } ], "responses": { From 7e78b95494afee3ba226dcc5905c15445cbb3e74 Mon Sep 17 00:00:00 2001 From: Mike Budzynski Date: Wed, 14 Apr 2021 16:18:21 -0700 Subject: [PATCH 4/4] Remove new query params --- .../2021-01-01-preview/apimcontenttypes.json | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json index 6becfb2e181d..f566930f5e1f 100644 --- a/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json +++ b/specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json @@ -267,20 +267,6 @@ }, { "$ref": "./apimanagement.json#/parameters/SubscriptionIdParameter" - }, - { - "name": "$filter", - "in": "query", - "required": false, - "type": "string", - "description": "Filters the results based on the provided query. Supported functions: `contains`, `startswith`, `endswith`, `eq`. Supported fields: any field from the properties object. For example, `$filter=contains(title,'test')`." - }, - { - "name": "$orderby", - "in": "query", - "required": false, - "type": "string", - "description": "Sorts the results by the provided property. Supported options: `asc`, `desc`. Supported fields: any field from the properties object. For example, `$orderby=en_us/title desc`." } ], "responses": {