Create API documentation and make new versions

Hello everyone,

We’ve been trying to create documentation for our API for a few weeks now, and we don’t yet know what software would make sense to do this with. The first tests with Postman were very promising, so I actually want to give the software the chance.

Unfortunately, I still have a few issues that we did not get solved.

In our company we develop the API with Java. There are annotations at each method for a short description of each method and Java creates an Open API 3.0 YAML file from it.
I was able to import this into Postman and saw all methods etc. there. The information from the annotations was also taken over.

Nevertheless, I have written additional documentation and texts within Postman for many methods, which are also visible in the documentation. For example, I added a table to one method with further explanations of the method. This is not possible to do as an annotation in Java and therefore has to be done by hand afterwards.

Now our API is constantly extended and we get new functions to the API. The Java department creates us again a new YAML file for version 2.0.

Now I want to import this new YAML file - as version 2.0. Of course the manual adjustments of the documentations from version 1.0 should be taken over.

I have already watched some video tutorial here, but exactly this requirement I have not seen until now.
I don’t know if this is the right approach, but the Java department provides us with the YAML file per version.

We would also like to do more with Postman here (load testing or automatic tests), but only once we have settled the issue with the documentation. We would like to have a professional training here, or even better a personal coaching, which would be exactly focused on our needs. But I haven’t found anything like that yet.

Many greetings,
Hauke