Searching for the updated Swagger documentation

[ruudg]

Hi,

I'm developing a Java library to communicate with Alfresco via REST API Services.

I downloaed YAML files from https://github.com/Alfresco/rest-api-explorer/tree/5.2.g/src/main/webapp/definitions  and I generated a CXF Client using https://editor.swagger.io/ 

I think that one of major benefits of using Swagger documentation is to give the possibility to auto-generate a client for developers that wants to easily consume the APIs.

I'm currently using an Alfresco 5.2.g and I verified that there are many differences between documentation and responses that I receive from Alfresco.

I also checked that on master branch of rest-api-explorer project the situation doesn't change. For example, alfresco-workflow.yaml last update is in 23 Feb 2017.

So my question is: am I searching Swagger documentation on the right place? Where can I find a manteined version of it?

Thanks in advance,

Ruud

[afaust · Accepted solution]

The GitHub project you looked in for newer definitions is the correct one. If there have not been any more updates than that is because there are none. The alfresco-workflow APIs should be considered "stable", as in "not going to be evolved much" because Alfresco is putting focus on enhancing standalone Activiti 7 / Cloud and Alfresco Process Service, and the embedded workflow engine (alfresco-workflow) is more or less bound to be removed at some point. It has actually been communicated as de-facto deprecated with Alfresco 6.0.

And yes, there are many differences between documentation and actual behaviour. The v1 ReSt API in Alfresco 5.2 was a first development state, and I would argue even now it is far from complete / sufficiently evolved to be considered final or stable. Unfortunately, the development process is not one of "API first", but of "ADF / UI first", so some operations are quite tailored to serving that UI framework instead of being generally useful.

[Jatherton]

https://github.com/Alfresco/alfresco-client-sdk