Hi Will, thank you for your help. I think that you already answered many of my questions.
I am implementing an API for a product that is based on Alfresco.
The API is used to manage some complex nested resources that are modelled as folders and contents in Alfresco.
To start, we need to implement some basic CRUD operations for the main resources and later we will add more functionalities. The hierarchy of the resources is complex and it is very important to choose the right tool to implement, document and maintain the API.
Because the API that I am writing will be based on Alfresco webscripts, I thought that it won't be possible to auto generate the code automatically. You confirmed that you haven't used any automation on the server side and this seems to confirm that it won't be possible without implementing a code generator by myself.
If this is true, the tool to choose will need to help with the documentation and the generation of the client code.
The set of APIs that I started to write is using Jackson for the json serialization and deserialization: the Alfresco webscripts manage java beans that are serialised and de-serialised.
To automatically document the API, I started to use RAML 1.0 because I liked how it defines types. Unfortunately, I found out that the current tool available does not work well with Jackson: it practically ignores all the Jackson annotations except @JsonProperty that is also used improperly. I even started to improve their implementation but if Alfresco is not using RAML anymore, I will probably revert to Swagger.
If I am not wrong, you have used the swagger annotations in the BPM module but not in the ECM module. I run some greps on the java code for the public API and I couldn't find any.