RFC: OpenAPI Adoption for Describing Uyuni HTTP API #100
Conversation
There was a problem hiding this comment.
Thanks for the research, @wweellddeerr. I posted a couple of questions below.
Other than that, some screenshots for the examples you provided would be great to give a rough idea.
Another question is about branding. Is it flexible enough that we can seamlessly integrate it to our look & feel?
| - Keep the documentation as it is, since it is stable and functional. | ||
| - The existing documentation, while static and less interactive, is stable and functional. Retaining it avoids the need for migration and eliminates the development and maintenance effort associated with Swagger integration. However, this approach would not address the limitations of static documentation, such as lack of interactivity and adherence to industry standards. | ||
|
|
||
| - Keep the format for describing the documentation using JavaDocs and write a new Java Doclet to generate the OpenAPI specification by parsing the definitions in JavaDocs. |
There was a problem hiding this comment.
I imagine we might still be obliged to have a non-interactive online documentation in parallel.
In this case, we should consider this alternative.
Can we generate such documentation from openAPI?
There was a problem hiding this comment.
That is a great question Can. We may need to have a static API documentation to integrate in the SUSE Documentation portal. @wweellddeerr can we make it with openAPI/swagger UI in build time?
There was a problem hiding this comment.
I would provide the specification exclusively in OpenAPI JSON format. However, I understand there may be requirements to support additional formats, such as static HTML.
It is totally possible to generate the JSON specification at build time, all we need is to collect all API Java classes and pass them through the custom reader and it will generate the JSON specification for publication.
If we also want to offer non-JSON formats, we can use swagger-codegen to generate static HTML or other formats. I will elaborate on this in the RFC.
|
|
||
| ##### A.3. XML-RPC API code examples | ||
|
|
||
| For XML-RPC endpoints, it is possible to provide a specific section in the web UI containing sample scripts. In addition to this, the `description` and `examples` fields of Swagger operation documentation can be used to aid understanding. |
There was a problem hiding this comment.
Can openAPI auto-generate code snippets as usage examples in any way?
How do we differentiate between XMLRPC and HTTP in the docs UI?
|
|
||
| ``` | ||
|
|
||
| For migrating the documentation of existing endpoints, this approach—defining the request body as an anonymous model—will be used. |
There was a problem hiding this comment.
Agree. It will make the migration simple, and avoid change the method definition, wich can lead to more changes or break the backward compatibility
| - Keep the documentation as it is, since it is stable and functional. | ||
| - The existing documentation, while static and less interactive, is stable and functional. Retaining it avoids the need for migration and eliminates the development and maintenance effort associated with Swagger integration. However, this approach would not address the limitations of static documentation, such as lack of interactivity and adherence to industry standards. | ||
|
|
||
| - Keep the format for describing the documentation using JavaDocs and write a new Java Doclet to generate the OpenAPI specification by parsing the definitions in JavaDocs. |
There was a problem hiding this comment.
That is a great question Can. We may need to have a static API documentation to integrate in the SUSE Documentation portal. @wweellddeerr can we make it with openAPI/swagger UI in build time?
| The expected outcome of this integration is to deliver Uyuni's API documentation as a valid OpenAPI JSON specification, complemented by an interactive Swagger UI integrated into Uyuni’s web interface, allowing users to explore and experiment with the API. | ||
|
|
||
|
|
||
| ### Detailed Design |
There was a problem hiding this comment.
In this design you are only mentioning the XML-RPC API which is also exposed through the JSON over HTTP API through the spark framework.
How about the API used by the Front-end? Should we also document it? Should it be documentation only internally or to end-users also?
| @Operation( | ||
| summary = "Update Content Environment", | ||
| tags = {"contentmanagement"}, | ||
| description = "Update Content Environment with given label", |
There was a problem hiding this comment.
During the migration process, we should try to generate the data to provide more information on how to use it on XML-RPC API also, so we can replace the existing static documentation and have more information to users.
See rendered version.