Use OpenAPI 3 specs file and simplify REST doc workflow

mibexsoftware · Feb 9, 2023 · 6d96ac3 · 6d96ac3
1 parent 537c1f5
commit 6d96ac3
Show file tree

Hide file tree

Showing 12 changed files with 770 additions and 626 deletions.
diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml
@@ -1,4 +1,4 @@
-name: Deploy Documentation
+name: Deploy Documentation 
 
 on:
   push:
@@ -10,16 +10,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v2
-        with:
-          node-version: 14.x
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run build
-      - name: Deploy to Github pages
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./web_deploy
+    - uses: actions/checkout@v2
+    - name: Deploy to Github pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: .
diff --git a/.yo-rc.json b/.yo-rc.json
diff --git a/README.md b/README.md
@@ -3,29 +3,16 @@
 ## Links
 
 - Documentation(ReDoc): https://mibexsoftware.github.io/repository-templates-rest-api/
-- Look full spec:
-    + JSON https://mibexsoftware.github.io/repository-templates-rest-api/swagger.json
-    + YAML https://mibexsoftware.github.io/repository-templates-rest-api/swagger.yaml
-- Preview spec version for branch `[branch]`: https://mibexsoftware.github.io/repository-templates-rest-api/preview/[branch]
 
-**Warning:** All above links are updated only after Travis CI finishes deployment
 
 ## Working on specification
-### Install
 
-1. Install [Node JS](https://nodejs.org/)
-2. Clone repo and `cd`
-    + Run `npm install`
-
-### Usage
-
-1. Run `npm start`
-2. Checkout console output to see where local server is started. You can use all [links](#links) (except `preview`) by replacing https://mibexsoftware.github.io/repository-templates-rest-api/ with url from the message: `Server started <url>`
-3. Make changes using your favorite editor or `swagger-editor` (look for URL in console output)
-4. All changes are immediately propagated to your local server, moreover all documentation pages will be automagically refreshed in a browser after each change
+1. Start a simple http server that watches your files e.g. `npx browser-sync start --server --files "*.html, *.json"`
+2. Make changes using your favorite editor or `swagger-editor` (look for URL in console output)
+3. All changes are immediately propagated to your local server, moreover all documentation pages will be automagically refreshed in a browser after each change
 **TIP:** you can open `swagger-editor`, documentation and `swagger-ui` in parallel
-5. Once you finish with the changes you can run tests using: `npm test`
-6. Share you changes with the rest of the world by pushing to GitHub :smile:
+**TIP:** use the redocly extension in VSCode, nice autocompletion and preview functions
+
 
 ### Deployment
 1. Merging to master will trigger a Github workflow deploying the latest changes
diff --git a/gulpfile.js b/gulpfile.js
diff --git a/index.html b/index.html
@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Repository Templates for Bitbucket Server REST API Specification</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+
+  <body>
+
+    <redoc id="redoc-container"></redoc>
+
+    <script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"></script>
+
+    <script>
+      Redoc.init('./swagger.json', {
+        hideDownloadButton: true
+      }, document.getElementById('redoc-container'))
+    </script>
+  </body>
+</html>
diff --git a/package.json b/package.json
diff --git a/scripts/build.js b/scripts/build.js
diff --git a/spec/README.md b/spec/README.md
diff --git a/spec/code_samples/README.md b/spec/code_samples/README.md