Swagger documentation for custom REST API

As we transition to the new Hyland Community, some post links may be temporarily disrupted as we finalize redirects. We apologize for the inconvenience and are working to resolve this as quickly as possible. Details.

luca_ow

Hi,

in our ACS-based projects we usually develop many custom REST APIs using the default extension points provided by Alfresco:

• XML descriptor (*.desc.xml)
• JAVA controller (extending org.springframework.extensions.webscripts.DeclarativeWebScript)
• JS controller
• FTL templates
• ecc

I would like to know if there is a way to document our custom APIs using Swagger and OAS (OpenAPI Specification) without handwriting the related YAML/JSON documentation files.

Swagger provide a rich framework to automatically produce API documentation by adding specific Java annotations to controllers but I don't find a way to use this framework with Alfresco WebScript.

Furthermore, we would like to easily use the "API first" approach (API First approach with Swagger) in our ACS-based projects so it would be also really important for us to find a way to produce REST APIs from the Swagger documentation files.

How does Alfresco handle API documentation in Alfresco REST API Explorer (GitHub - Alfresco/rest-api-explorer: Public REST API Explorer)?

In GitHub I found the YAML definition files (https://github.com/Alfresco/rest-api-explorer/tree/master/src/main/webapp/definitions) but I have no idea how Alfresco produces/maintains these files and if these files are also used to automatically produce WebScript definition components (at least the java controllers).

Thank you in advance!

kerkhofsd

About the 'API first approach': 

There already is some tooling around to generate source code from OpenAPI / Swagger documentation, e.g. swagger-api/swagger-codegen or OpenAPITools/openapi-generator. 

From my experience with these tools, I think it might be possible to use it in the context of Alfresco if the generators are provided with the correct templates. 

I wonder if someone already tried creating such templates for auto-generating Alfresco WebScripts? Might be a good Hack-a-thon project :-)?