AnsweredAssumed Answered

Swagger documentation for custom REST API

Question asked by luca_ow on Mar 29, 2018

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!

Outcomes