topic Re: swagger vs raml in Alfresco Forum

swagger vs raml

marco_altieri — Mon, 01 May 2017 18:54:49 GMT

This is a question that probably can only be answered by Alfresco engineers.The Alfresco BPM has a nice set of APIs that are documented using RAML.The Alfresco ECM has also a set of APIs that are documented with Swagger.Is there a plan to use the same framework for the two platforms ?

Re: swagger vs raml

eugenio_romano — Tue, 02 May 2017 16:59:31 GMT

Hi Marco,

Alfresco Business process has Swagger as well from version 1.6.0

Eugenio

Re: swagger vs raml

marco_altieri — Tue, 02 May 2017 22:42:38 GMT

Thank you Eugenio.

Do you know if Alfresco has used Swagger only to document the APIs or also to generate the code (for the client and the server side)?

If Swagger has been used only for the documentation, was the documentation produced automatically or written manually?

Thanks

Re: swagger vs raml

wabson — Thu, 04 May 2017 11:14:59 GMT

Hi Marco, we use SpringFox to generate the API spec dynamically from annotations in the Process Services code, whilst not technically a Swagger product we do use the official Swagger annotations. SpringFox also bundles a version of Swagger-UI, which we are moving to using as a reference for the API docs.

Regarding codegen, we have also used Swagger codegen to generate the initial set of bindings inside the Alfresco JavaScript API. There has been no codegen used on the server side.

What is your interest in Swagger and can you elaborate on why these are important concerns to you? Maybe we can share a little more if we understand your use-case.

Thanks,

Will

Re: swagger vs raml

marco_altieri — Thu, 04 May 2017 14:40:16 GMT

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.