-
Notifications
You must be signed in to change notification settings - Fork 2.8k
Description
Umbraco's management API exposes provides many endpoints for CRUD and other operations on Umbraco entities. They are all defined in the Umbraco.Cms.Api.Management project in controllers under the Umbraco.Cms.Api.Management.Controllers.
Each public action method in the controllers support two attrbutes: EndpointSummary and EndpointDescription. The former is intended for short description of the endpoint and the latter for a longer one.
In #20549 these attributes have been populated for a small subset of controller methods.
We'd like to apply these same attributes to all management API controller action methods with appropriate short and long descriptions. You should use the attributes populated in the linked PR as good examples for the types of descriptions we would like to use. The descriptions should all use the same tense (e.g. "Gets a data type" rather than "Get a data type"), use similar phrases when describing similar concepts like "pagination" or "collection", be punctuated consistently and contain a similar amount of detail.
EndpointSummary should be one short sentence. EndpointDescription should be a maximum of three sentences.
The aim should be to not create an undue burden on ourselves going forward in describing every field or parameter, and to avoid repeating something that's already easily available in the Swagger UI that shows request and response models and parameters. We should try to give details on the end result of the operation describing what calling the method means in terms of the system behaviour.
Avoid adding descriptions to those that already have them in #20549, but please add them to all of the others.