HDDS-11300. Update Swagger documentation for Recon APIs

[VarshaRaviCV]

What changes were proposed in this pull request?

HDDS-11300. Update Swagger documentation for Recon APIs

The below API endpoints are missing from the swagger specification.

GET /api/v1/volumes: Fetches all volumes in the cluster.
GET /api/v1/buckets: Fetches all buckets in the cluster.
GET /api/v1/containers/deleted: Fetches all the deleted containers in the cluster.
GET /api/v1/keys/open/summary: Fetches the summary of open keys in the cluster.
GET /api/v1/keys/deletePending/summary: Fetches the summary of keys pending deletion in the cluster.
GET /api/v1/keys/deletePending/dirs/summary: Fetches the summary of the dirs pending deletion in the cluster.
GET /api/v1/datanodes/decommission/info: Fetches the info about all datanodes being decommissioned in the cluster.
GET /api/v1/datanodes/decommission/info/datanode: Fetches the info about a particular datanodes being decommissioned in the cluster.

What is the link to the Apache JIRA

https://issues.apache.org/jira/browse/HDDS-11300

How was this patch tested?

Built the project locally, started ozone on docker and verified the docs.
The doc changes are present on the below URL locally.

http://localhost:9874/docs/interface/swaggerreconapi.html#/

[devabhishekpal]

Thanks @VarshaRaviCV for the patch. I am still review the PR, but had a minor nit.

Can we avoid shifting all the responses to component/schemas?
While this is not going to affect the final working i.e anything under component can be referenced in other places so whether it is under schemas section or responses section it won't matter - but logically:

• schemas should have resuable data models (ex: ACL, VersionLocation, ReplicaHistory, LocationList etc.)
• responses should have the final model of the response - which would ideally make use of the common schemas via refs.

For example:

DeletePendingKeys:
      type: object
      properties:
        lastKey:
          type: string
          example: sampleVol/bucketOne/key_one
        ......
        deletedKeyInfo:
          type: array
          items:
            type: object
            properties:
              omKeyInfoList:
                $ref: "#/components/schemas/OMKeyInfoList"
              ...
         ...

This should be a response and OMKeyInfoList being a data type/model should be under schemas.

It is okay if you want to address this in a separate PR, as I believe in the original changes we have a few such cases as well - and this would overall be outside the scope of this PR.
In that case could you help revert to the original changes for existing lines (i.e originally if it was in responses section we should not move to schemas) - this will help clean up the changes a bit - and we can take up organizing the sections later on if we want.

I will verify and check the response structures in the meantime

[VarshaRaviCV]

@devabhishekpal Thanks for the clarification. Like we talked about offline, the open API specification mentions responses as a whole can be defined under the components/responses if they are re-used. The schema for the responses should be defined in the components/schemas section only. The existing version of recon-api.yaml uses the responses like a schema which is a structural error based on open api specification.

[devabhishekpal]

Thanks @VarshaRaviCV for pointing out the inconsistency in existing code with regards to OpenAPI specification and also the fix. Please let the current changes be present.