topic Swagger documentation for custom REST API in Alfresco Forum https://connect.hyland.com/t5/alfresco-forum/swagger-documentation-for-custom-rest-api/m-p/78039#M24459 <HTML><HEAD></HEAD><BODY><P>Hi,</P><P>in our ACS-based projects we usually&nbsp;develop&nbsp;many custom REST APIs using the default extension points provided by Alfresco:</P><UL><LI>XML descriptor (*.desc.xml)</LI><LI>JAVA controller (extending&nbsp;org.springframework.extensions.webscripts.DeclarativeWebScript)</LI><LI>JS controller</LI><LI>FTL templates</LI><LI>ecc</LI></UL><P></P><P>I would like to know if&nbsp;there is a way to document our custom APIs using Swagger and OAS (OpenAPI Specification) without handwriting the related YAML/JSON documentation files.</P><P>Swagger provide a rich framework to automatically produce API documentation&nbsp;by adding specific Java annotations to controllers but I don't&nbsp;find a way to use this framework with Alfresco&nbsp;WebScript.</P><P></P><P>Furthermore, we&nbsp;would like to easily use the "API first" approach (<A class="link-titled" href="https://www.easyitblog.info/2017/01/08/api-first-approach-with-swagger/" title="https://www.easyitblog.info/2017/01/08/api-first-approach-with-swagger/" rel="nofollow noopener noreferrer">API First approach with Swagger</A>) 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.</P><P></P><P>How does Alfresco&nbsp;handle API documentation in&nbsp;Alfresco REST API Explorer (<A class="link-titled" href="https://github.com/Alfresco/rest-api-explorer" title="https://github.com/Alfresco/rest-api-explorer" rel="nofollow noopener noreferrer">GitHub - Alfresco/rest-api-explorer: Public REST API Explorer</A>)?</P><P>In GitHub I found the YAML definition files (<A class="link-titled" href="https://github.com/Alfresco/rest-api-explorer/tree/master/src/main/webapp/definitions" title="https://github.com/Alfresco/rest-api-explorer/tree/master/src/main/webapp/definitions" rel="nofollow noopener noreferrer">https://github.com/Alfresco/rest-api-explorer/tree/master/src/main/webapp/definitions</A>) but I have no idea how Alfresco produces/maintains these files and if these files are also used to automatically produce WebScript&nbsp;definition components (at least the java controllers).</P><P></P><P>Thank you in advance!</P></BODY></HTML> Thu, 29 Mar 2018 12:43:33 GMT luca_ow 2018-03-29T12:43:33Z Swagger documentation for custom REST API https://connect.hyland.com/t5/alfresco-forum/swagger-documentation-for-custom-rest-api/m-p/78039#M24459 Hi,in our ACS-based projects we usually&nbsp;develop&nbsp;many custom REST APIs using the default extension points provided by Alfresco:XML descriptor (*.desc.xml)JAVA controller (extending&nbsp;org.springframework.extensions.webscripts.DeclarativeWebScript)JS controllerFTL templateseccI would like to know if&nbsp;ther Thu, 29 Mar 2018 12:43:33 GMT https://connect.hyland.com/t5/alfresco-forum/swagger-documentation-for-custom-rest-api/m-p/78039#M24459 luca_ow 2018-03-29T12:43:33Z Re: Swagger documentation for custom REST API https://connect.hyland.com/t5/alfresco-forum/swagger-documentation-for-custom-rest-api/m-p/78040#M24460 <HTML><HEAD></HEAD><BODY><P>About the 'API first approach':&nbsp;</P><P>There already is some tooling around to generate&nbsp;source code from OpenAPI / Swagger documentation, e.g. <A href="https://github.com/swagger-api/swagger-codegen" rel="nofollow noopener noreferrer">swagger-api/swagger-codegen</A> or <A href="https://github.com/OpenAPITools/openapi-generator" rel="nofollow noopener noreferrer">OpenAPITools/openapi-generator</A>.&nbsp;</P><P>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.&nbsp;</P><P></P><P>I&nbsp;wonder if someone already tried creating&nbsp;such templates for auto-generating Alfresco WebScripts? Might be a good Hack-a-thon project :-)?</P></BODY></HTML> Fri, 19 Jul 2019 08:24:02 GMT https://connect.hyland.com/t5/alfresco-forum/swagger-documentation-for-custom-rest-api/m-p/78040#M24460 kerkhofsd 2019-07-19T08:24:02Z