Automating process of maintaining REST API Catalogs

[Mariangela]

Description:

Existing method

When adding REST API catalogs we carryout the following steps:

1. Download the YAML from the product APK repo (e.g., [2])

2. Save it in en/docs/catalogs directory in the docs-apk repo

3. Refer to the YAML in the respective MD file. (e.g., en/docs/catalogs/api-reference-developer-portal.md)

     Example:
     ```
     ---
     template: templates/redoc.html
     ---
   
     <redoc spec-url='{{base_path}}/catalogs/devportal-api.yaml'></redoc>
     <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
     ```
   

   The REST API catalog will rendered as expected. (e.g., https://apk.docs.wso2.com/en/latest/catalogs/api-reference-developer-portal/)

Disadvantage of the above method

• Every time changes are done to the REST API YAML file in the APK product repo (wso2/apk [1]), we have to manually copy the YAML file and and add it to the APK docs repo (wso2/docs-apk [2] repo).
• There is a high possibility that the content in the APK docs will be outdated because APK devs may not remember alert when changes are done in the REST API YAML docs.

[1] https://github.com/wso2/apk
[2] https://github.com/wso2/docs-apk

Proposed Fix

@sanjeewa-malalgoda suggested to also get the https://github.com/wso2/apk repo to build as well in the APK build script [3]. So that we can automate the process.

Note

When trying to add the APK product repo GitHub URL directly in the APK docs repo MD file the REST API Catalog does not work.

---
template: templates/redoc.html
---

<redoc spec-url='[{{base_path}}/catalogs/devportal-api.yaml](https://github.com/wso2/apk/blob/main/devportal/devportal-domain-service/ballerina/resources/devportal-api.yaml)'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>

[1] en/docs/catalogs/api-reference-developer-portal.md
[2] https://github.com/wso2/apk/blob/main/devportal/devportal-domain-service/ballerina/resources/devportal-api.yaml
[3] https://wso2.org/jenkins/job/docs/job/docs-apk/configure

[chanaka3d]

This issue is fixed in the dev environment. Please check and confirm.