REST API Doc via Swagger UI Annotations

[jdcmsd]

Task

This one gigantic task will track the progress of API doc by way of Swagger UI annotations. This is the all-important "first go," after the completion of which all future API doc will be tolerably dainty and piecemeal. But this first one is a mountain of an ogre, and thus merits the epic tag.

There are 500+ endpoints, and the current rock is to have 25 finished by mid-July 2024. I anticipate the rate will pick up once I've settled into a comfortable cadence — perhaps a loping stride.

In addition to per-endpoint documentation, this process will include better use of tags, ordering, and other organization level ups.

Proposed Objective

Documentation

Proposed Priority

Priority 1 - Show Stopper

Acceptance Criteria

All of them.

Document. All. Of. Them.

Sub-Tasks & Estimates

• Alphabetize operations within tags
• More elaborate and granular tagging practices
  • More categories
  • Better ordering of categories
• Document all of them.
  • /v1/workflow
    • Workflow API swagger doc, Part 1 #29189
    • Swaggify Workflow API, part 2 #29828
    • Fixing the two octet-stream Workflow endpoints #30167 (fix)
    • Workflow Import endpoint: schema & error messages incorrect #29730 (fix)
    • API Playground locks up when opening endpoint with multipart form #29211 (fix)
    • Workflow: Moving some API Response annotations to the class #30985
  • Swagger Documentation for /v1/contenttype Endpoints #29037
  • /v1/content #29082
  • Document PageResource endpoint using Swagger #29089
  • Swagger Documentation for /v1/api-token Endpoints #29742
  • Authentication API Swagger Documentation #29616
  • /bundle
  • /v1/nav
  • /v1/experiments
  • /v1/dotsaml
  • /v1/dotcdn
  • /v1/fieldTypes
  • /ext/license
  • /osgi-info
  • /auditPublishing
  • /bundlePublisher
  • /config
  • /cluster
  • /environment
  • /integrity
  • /portlet
  • /license
  • /osgi
  • /v1/publishqueue
  • /restexample
  • /role
  • /rulesengine
  • /structure
  • /v1/tags
  • /testResource
  • /util
  • /widget
  • /v1/apps
  • /v1/forgotpassword
  • /v1/loginform
  • /v1/logout
  • /v1/changePassword
  • /v1/browser
  • /v1/categories
  • /v1/containers
  • /ws/v1/system
  • /v1/folder
  • /v1/form
  • /v1/esindex
  • /v1/languages
  • /v1/jvm
  • /v1/maintenance
  • /v1/menu
  • /v1/notification
  • /v1/personalization
  • /v1/personas
  • /v1/portlet
  • /v1/toolgroups
  • /v1/pushpublish
  • /v1/relationships
  • /v1/site
  • /v1/sites
  • /v1/appconfiguration
  • /v1/configuration
  • /v1/upgradetask
  • /v1/caches
  • /v1/system
  • /v1/logger
  • /v1/system-status
  • /v1/permissions
  • /v1/redis
  • /v1/roles
  • /v1/temp
  • /v1/templates
  • /v1/themes
  • /v1/users
  • /v1/versionables
  • /vtl
  • /v2/contenttype
  • /v2/languages
  • /v3/contenttype
  • /es/layout
  • /es/search
  • /es/raw
  • /personas
  • /application.wadl
  • /v1/logs
  • [ADD MORE AS NEEDED; THERE ARE MANY MORE]

[jdcmsd]

Will just paste PRs into the main post rather than doing the development-sidebar link thing.