API docs workflow improvements
backlog
R
Rachana Visavadiya
Currently, there is no proper workflow to submit the API changes for review.
Some of the options we require are as follows:
* Submit API changes for review.
* Find the exact endpoint that was updated.
* View the changes made to any specific API endpoint topic.
Log In
D
D360 Product Management
backlog
D
D360 Product Management
under review
D
D360 Product Management
Rachana Visavadiya, Thank you for the detailed explanation! We will review this request and consider incorporating it based on upvotes and our internal evaluation.
D
D360 Product Management
Hi Rachana Visavadiya, Thank you for your feedback! Could you please elaborate on your use case and specific scenarios where these options would be useful? This will help us better understand your requirements and prioritize this request effectively.
R
Rachana Visavadiya
D360 Product Management Thank you for getting back to us! :)
In our case, the source of the REST API endpoints is a GitHub repo with 12 YAML files for different categories of the APIs. When we update the YAML files and resync in Document360, the entire file is in the draft state. It is difficult to know the exact changes made to a YAML file. For example, if only one endpoint was updated in a YAML file, it is not possible to know the details from Document360.
Similar to the workflow in the normal documentation, we would like to have a review process for APIs. We need to assign the updated API files to the reviewer/publisher. Right now, we can resync the endpoints. However, due to user permissions, we have to manually let the reviewers know about the file changes and request them to publish the APIs. This creates bottlenecks in the documentation process.
We also need the reviewers to be able to see the specific changes made in the YAML file. The "Revision history" for the APIs is not very user-friendly at this time, as we cannot find the changes made to an entire file. The reviewer would need to access the GitHub repo to find the changes.
Thus, we request an improved review process for API documentation. Please let me know if you need further details! Thank you!