devmadhuu commented on code in PR #5509: URL: https://github.com/apache/ozone/pull/5509#discussion_r1381933147
########## hadoop-hdds/docs/themes/ozonedoc/static/swagger-resources/recon-api.yaml: ########## @@ -0,0 +1,1584 @@ +openapi: 3.0.0 +info: + title: Ozone Recon REST API + license: + url: http://www.apache.org/licenses/LICENSE-2.0.html + name: Apache 2.0 License +servers: + - url: /api/v1/ +tags: + - name: Containers and Keys + description: APIs to fetch information about the available containers and keys. **Admin Only** + - name: Blocks Metadata + description: APIs to fetch metadata for the blocks available. **Admin Only** + - name: Namespace Metadata + description: APIs to fetch metadata for the namespace. **Admin Only** + - name: Cluster State + description: APIs to fetch data about the cluster state + - name: Datanodes + description: APIs to fetch data about the Datanodes + - name: Pipelines + description: APIs to fetch data about the Pipelines + - name: Tasks + description: APIs to fetch data about status of Recon Tasks + - name: Utilization + description: APIs to fetch data about space utilization + - name: Metrics + description: APIs to fetch data about various metrics from Prometheus + externalDocs: + description: Prometheus API docs + url: https://prometheus.io/docs/prometheus/latest/querying/api/ +paths: + /containers: + get: + tags: + - Containers and Keys + summary: Get all Container Metadata information + operationId: getContainerInfo + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/ContainerMetadata' + /containers/{containerId}/keys: Review Comment: > So here `containerId` is a placeholder for `id` in the documentation: `/api/v1/containers/:id/keys` > > Swagger does not support naming of paths like that. From [swagger docs](https://swagger.io/docs/specification/describing-parameters/#path-parameters): > > `Path parameters are variable parts of a URL path. They are typically used to point to a specific resource within a collection, such as a user identified by ID. A URL can have several path parameters, each denoted with curly braces { }.` > > What this basically means is, when we are interacting with the swagger UI, if we click `Try It Out`, we can provide parameters to the UI, check in the attached screenshot containerId is provided as `111`. Now in the sample cURL call provided (red highlight), you will notice the url as: `'http://localhost:1313/api/v1/containers/111/keys.....` <img alt="Screenshot 2023-11-03 at 21 13 50" width="1728" src="https://user-images.githubusercontent.com/43001336/280336503-e5b678e3-73ed-4538-bf4d-7133b4c0004e.png";> > > Here the 111 is defined to be placed as a path parameter, and is replaced in the `{containerId}` part of the URL. The second type is the query parameter, which appears as `?prevKey=%2Fvol1%2Fbucket1%2Fkey1&limit=1000` in the URL. Not necessarily the code format, just `id` inline with code makes sense along with description of param. If possible, then inline with code makes more sense. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
![https://user-images.githubusercontent.com/43001336/280336503-e5b678e3-73ed-4538-bf4d-7133b4c0004e.png"](https://user-images.githubusercontent.com/43001336/280336503-e5b678e3-73ed-4538-bf4d-7133b4c0004e.png"){kind=link}