Swagger Documentation for /v1/api-token Endpoints

[gavriella-dotcms]

Parent Issue

28600

Task

Add Swagger documentation to api-token endpoints.

Proposed Objective

Documentation

Proposed Priority

Priority 3 - Average

Acceptance Criteria

Add endpoints should contain the following information in playground:

• Tags
• Descriptions
• Parameters
• Request bodies
• Example values if necessary
• Return schema

External Links... Slack Conversations, Support Tickets, Figma Designs, etc.

No response

Assumptions & Initiation Needs

No response

Quality Assurance Notes & Workarounds

No response

Sub-Tasks & Estimates

Endpoints being documented:

• /v1/apitoken
• /v1/apitoken/{tokenId}
• /v1/apitoken/{tokenId}/jwt
• /v1/apitoken/{tokenId}/revoke
• /v1/apitoken/{userId}/tokens
• /v1/apitoken/remote
• /v1/apitoken/users/{userid}/revoke
• /v1/apitoken/users/revoke

[valentinogiardino]

IQA FAILED

Tested on trunk_477606b

You can view the detailed findings here: Document.

In summary, I found inconsistencies between the response descriptions and the actual outputs returned by the endpoints. There are also some typos and discrepancies in the parameter names.

I couldn't test the POST request as it returns a 400 error. This might be due to an issue with the body I'm passing, but I haven't identified the exact problem. The PUT /api/v1/apitoken/remote request also failed, returning a 500 error with the following message:

"message": "Index 251 out of bounds for length 65"

[jdcmsd]

Good comments in that doc. I'll do a review as well as soon as I can. That said, that /remote endpoint's out-of-bounds error likely points to a value mismatch of some sort; Gavriella was getting it while using dummy values (like "expirationSeconds": "0") but it went away with appropriate values in a push-publishing enabled environment, such as this:

https://github.com/dotCMS/core/tree/master/docker/docker-compose-examples/push-publish

For example, I was able to succeed with the following data payload from the (8081) sender environment:

{
  "token": {
    "network": "0.0.0.0/0",
    "expirationSeconds": "100",
    "claims": {
      "label": "Push Publish"
    }
  },
  "remote": {
    "host": "dotcms-receiver.local",
    "port": "8082",
    "protocol": "http"
  },
  "auth": {
    "login": "[email protected]",
    "password": "YWRtaW4="
  }
}

[valentinogiardino]

IQA PASSED

Tested on trunk_7d5223d
All inconsistencies identified in the previous IQA have been resolved.

[bryanboza]

Fixed, tested in the last trunk and now the doc looks ok