Swagger documentation for custom REST API

[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 :-)?