Skip to content

Commit 5047dfd

Browse files
mikebudzynskimikebudzynski
authored
APIM: improve developer portal operations docs (#13941)
* APIM: improve the documentation for dev portal operations * Minor changes * Removing OData parameters from the stable API version * Remove new query params
1 parent 09d826c commit 5047dfd

File tree

5 files changed

+95
-95
lines changed

5 files changed

+95
-95
lines changed

‎specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimcontenttypes.json‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040
"ContentType"
4141
],
4242
"operationId": "ContentType_ListByService",
43-
"description": "Returns list of content types",
43+
"description": "Lists the developer portal's content types. Content types describe content items' properties, validation rules, and constraints.",
4444
"x-ms-examples": {
4545
"ApiManagementListContentTypes": {
4646
"$ref": "./examples/ApiManagementListContentTypes.json"
@@ -62,7 +62,7 @@
6262
],
6363
"responses": {
6464
"200": {
65-
"description": "Lists a collection of content type entities.",
65+
"description": "Returns a collection of the Content Type entities.",
6666
"schema": {
6767
"$ref": "./definitions.json#/definitions/ContentTypeCollection"
6868
}
@@ -85,7 +85,7 @@
8585
"ContentType"
8686
],
8787
"operationId": "ContentType_Get",
88-
"description": "Gets API Management content type details.",
88+
"description": "Gets the details of the developer portal's content type. Content types describe content items' properties, validation rules, and constraints.",
8989
"x-ms-examples": {
9090
"ApiManagementGetContentType": {
9191
"$ref": "./examples/ApiManagementGetContentType.json"
@@ -110,7 +110,7 @@
110110
],
111111
"responses": {
112112
"200": {
113-
"description": "Get the details of the content type.",
113+
"description": "Returns the details of the specified content type.",
114114
"schema": {
115115
"$ref": "./definitions.json#/definitions/ContentTypeContract"
116116
},
@@ -134,7 +134,7 @@
134134
"ContentType"
135135
],
136136
"operationId": "ContentType_CreateOrUpdate",
137-
"description": "Creates or updates an Content Type.",
137+
"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.",
138138
"x-ms-examples": {
139139
"ApiManagementCreateContentType": {
140140
"$ref": "./examples/ApiManagementCreateContentType.json"
@@ -162,7 +162,7 @@
162162
],
163163
"responses": {
164164
"201": {
165-
"description": "Content type was successfully created.",
165+
"description": "The content type was successfully created.",
166166
"headers": {
167167
"ETag": {
168168
"description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.",
@@ -198,7 +198,7 @@
198198
"ContentType"
199199
],
200200
"operationId": "ContentType_Delete",
201-
"description": "Removes specified content type.",
201+
"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.",
202202
"x-ms-examples": {
203203
"ApiManagementDeleteContentType": {
204204
"$ref": "./examples/ApiManagementDeleteContentType.json"
@@ -246,7 +246,7 @@
246246
"ContentTypeContentItem"
247247
],
248248
"operationId": "ContentItem_ListByService",
249-
"description": "Returns list of content items",
249+
"description": "Lists developer portal's content items specified by the provided content type.",
250250
"x-ms-examples": {
251251
"ApiManagementListContentTypeContentItems": {
252252
"$ref": "./examples/ApiManagementListContentTypeContentItems.json"
@@ -271,7 +271,7 @@
271271
],
272272
"responses": {
273273
"200": {
274-
"description": "Lists a collection of Content Type entities.",
274+
"description": "Returns a collection of Content Type entities.",
275275
"schema": {
276276
"$ref": "./definitions.json#/definitions/ContentItemCollection"
277277
}
@@ -294,7 +294,7 @@
294294
"ContentTypeContentItem"
295295
],
296296
"operationId": "ContentItem_GetEntityTag",
297-
"description": "Returns content item metadata",
297+
"description": "Returns the entity state (ETag) version of the developer portal's content item specified by its identifier.",
298298
"x-ms-examples": {
299299
"ApiManagementHeadContentTypeContentItem": {
300300
"$ref": "./examples/ApiManagementHeadContentTypeContentItem.json"
@@ -343,7 +343,7 @@
343343
"ContentTypeContentItem"
344344
],
345345
"operationId": "ContentItem_Get",
346-
"description": "Returns content item details",
346+
"description": "Returns the developer portal's content item specified by its identifier.",
347347
"x-ms-examples": {
348348
"ApiManagementGetContentTypeContentItem": {
349349
"$ref": "./examples/ApiManagementGetContentTypeContentItem.json"
@@ -371,7 +371,7 @@
371371
],
372372
"responses": {
373373
"200": {
374-
"description": "Get the details of the content item.",
374+
"description": "Returns the content item.",
375375
"schema": {
376376
"$ref": "./definitions.json#/definitions/ContentItemContract"
377377
},
@@ -395,7 +395,7 @@
395395
"ContentTypeContentItem"
396396
],
397397
"operationId": "ContentItem_CreateOrUpdate",
398-
"description": "Creates new content item",
398+
"description": "Creates a new developer portal's content item specified by the provided content type.",
399399
"x-ms-examples": {
400400
"ApiManagementCreateContentTypeContentItem": {
401401
"$ref": "./examples/ApiManagementCreateContentTypeContentItem.json"
@@ -426,7 +426,7 @@
426426
],
427427
"responses": {
428428
"201": {
429-
"description": "Content item was successfully created.",
429+
"description": "The content item was successfully created.",
430430
"headers": {
431431
"ETag": {
432432
"description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.",
@@ -462,7 +462,7 @@
462462
"ContentTypeContentItem"
463463
],
464464
"operationId": "ContentItem_Delete",
465-
"description": "Removes specified content item.",
465+
"description": "Removes the specified developer portal's content item.",
466466
"x-ms-examples": {
467467
"ApiManagementDeleteContentTypeContentItem": {
468468
"$ref": "./examples/ApiManagementDeleteContentTypeContentItem.json"

‎specification/apimanagement/resource-manager/Microsoft.ApiManagement/preview/2021-01-01-preview/apimportalrevisions.json‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040
"PortalRevision"
4141
],
4242
"operationId": "PortalRevision_ListByService",
43-
"description": "Lists a collection of developer portal revision entities.",
43+
"description": "Lists developer portal's revisions.",
4444
"x-ms-examples": {
4545
"ApiManagementListPortalRevisions": {
4646
"$ref": "./examples/ApiManagementListPortalRevisions.json"
@@ -75,7 +75,7 @@
7575
],
7676
"responses": {
7777
"200": {
78-
"description": "Lists a collection of developer portal revision entities.",
78+
"description": "Lists portal's revisions.",
7979
"schema": {
8080
"$ref": "./definitions.json#/definitions/PortalRevisionCollection"
8181
}
@@ -98,7 +98,7 @@
9898
"PortalRevision"
9999
],
100100
"operationId": "PortalRevision_GetEntityTag",
101-
"description": "Gets developer portal revision specified by its identifier.",
101+
"description": "Gets the developer portal revision specified by its identifier.",
102102
"x-ms-examples": {
103103
"ApiManagementHeadPortalRevision": {
104104
"$ref": "./examples/ApiManagementHeadPortalRevision.json"
@@ -123,7 +123,7 @@
123123
],
124124
"responses": {
125125
"200": {
126-
"description": "Specified Portal revision entity exists and current entity state version is present in the ETag header.",
126+
"description": "The specified portal revision entity exists and current entity state version is present in the ETag header.",
127127
"headers": {
128128
"ETag": {
129129
"description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.",
@@ -144,7 +144,7 @@
144144
"PortalRevision"
145145
],
146146
"operationId": "PortalRevision_Get",
147-
"description": "Gets developer portal revision specified by its identifier.",
147+
"description": "Gets the developer portal's revision specified by its identifier.",
148148
"x-ms-examples": {
149149
"ApiManagementGetPortalRevision": {
150150
"$ref": "./examples/ApiManagementGetPortalRevision.json"
@@ -169,7 +169,7 @@
169169
],
170170
"responses": {
171171
"200": {
172-
"description": "Gets the specified developer portal revision entity.",
172+
"description": "Gets the specified portal's revision.",
173173
"schema": {
174174
"$ref": "./definitions.json#/definitions/PortalRevisionContract"
175175
},
@@ -193,7 +193,7 @@
193193
"PortalRevision"
194194
],
195195
"operationId": "PortalRevision_CreateOrUpdate",
196-
"description": "Creates a new developer portal revision.",
196+
"description": "Creates a new developer portal's revision by running the portal's publishing. The `isCurrent` property indicates if the revision is publicly accessible.",
197197
"x-ms-examples": {
198198
"ApiManagementCreatePortalRevision": {
199199
"$ref": "./examples/ApiManagementCreatePortalRevision.json"
@@ -226,10 +226,10 @@
226226
],
227227
"responses": {
228228
"202": {
229-
"description": "Request to create developer portal revision was accepted."
229+
"description": "Request to create a developer portal revision was accepted."
230230
},
231231
"201": {
232-
"description": "Developer portal revision was successfully created.",
232+
"description": "The developer portal revision was successfully created.",
233233
"schema": {
234234
"$ref": "./definitions.json#/definitions/PortalRevisionContract"
235235
},

0 commit comments

Comments
 (0)