Merge pull request #189 from xenit-eu/ALFREDAPI-536/alfred-api-docs

Alfredapi-536: alfred-api-docs

.github/pull_request_template.md

@@ -3,7 +3,7 @@ Fixes https://xenitsupport.jira.com/browse/ALFREDAPI-<**YOUR TICKET ID**>
 - [ ] Is [CHANGELOG.md](https://github.com/xenit-eu/alfred-api/blob/master/CHANGELOG.md) extended?
 - [ ] Does this PR avoid breaking the API? 
     Breaking changes include adding, changing or removing endpoints and/or JSON objects used in requests and responses.
-- [ ] Does the PR comply to REST HTTP result codes policy outlined in the [user guide](https://docs.xenit.eu/alfred-api/stable-user/rest-api/index.html#rest-http-result-codes)?
+- [ ] Does the PR comply to REST HTTP result codes policy outlined in the [user guide](https://docs.xenit.eu/alfred-api/user/rest-api/index.html#rest-http-result-codes)?
 - [ ] Is error handling done through a method annotated with `@ExceptionHandler` in the webscript classes?
 - [ ] Does the PR follow our [coding styleguide and other active procedures](https://xenitsupport.jira.com/wiki/spaces/XEN/pages/624558081/XeniT+Enhancement+Proposals+XEP)?
 - [ ] Is usage of `this.` prefix avoided?

CHANGELOG.md

@@ -14,7 +14,8 @@ This release also drop* support for Alfresco 6.2 and adds support for 7.4.
 
 ### Changed
 * [ALFREDAPI-527](https://xenitsupport.jira.com/browse/ALFREDAPI-527):
-Alfresco containers use port 8080 now instead of ephemeral ports
+Alfresco containers use port 8080 now instead of ephemeral ports 
+* [ALFREDAPI-536](https://xenitsupport.jira.com/browse/ALFREDAPI-536): Reabsorb alfred-api-docs repo into this
 
 ### Fixed
 * [ALFREDAPI-520](https://xenitsupport.jira.com/browse/ALFREDAPI-520): Enforce encoding on bulk json responses to guarantee clean text

README.md

@@ -19,7 +19,7 @@ are not supported by the Alfresco Public API.
 
 
 ## Usage
-Full documentation can be found at the [project's documentation](https://docs.xenit.eu/alfred-api/stable-user/index.html).
+Full documentation can be found at the [project's documentation](https://docs.xenit.eu/alfred-api/).
 
 ## Contributing
 
@@ -33,7 +33,7 @@ Full documentation can be found at the [project's documentation](https://docs.xe
     * Add a note to the changelog with upgrade instructions
     * Notify all customers at the next release
 * When working in REST code, please comply to **REST HTTP result codes** policy outlined in the
-  [user guide](https://docs.xenit.eu/alfred-api/stable-user/rest-api/index.html#rest-http-result-codes).
+  [user guide](https://docs.xenit.eu/alfred-api/user/rest-api/index.html#rest-http-result-codes).
 * Prefer unit tests over integration tests to keep builds fast
 * Avoid `this.` prefix for consistency (unless the scope is ambiguous).
 * Follow our [coding styleguide and other active procedures](https://xenitsupport.jira.com/wiki/spaces/XEN/pages/624558081/XeniT+Enhancement+Proposals+XEP).
@@ -69,7 +69,7 @@ However, this starts (and afterwards stops) docker containers. This includes sta
  adding a startup time of several minutes. To circumvent this you also run the test on already running containers with
  for example:
  ```bash
-./gradlew -x composeUp -x composeDown :apix-integrationtests:test-61:integrationTest -Pprotocol=http -Phost=localhost -Pport=8061
+./gradlew -x composeUp -x composeDown :apix-integrationtests:alfresco:74:integrationTest -Pprotocol=http -Phost=localhost -Pport=8074
 ```
 
 If you only want to run specific tests, you can specify this on the Gradle invocation with a pattern. For example:
@@ -86,28 +86,3 @@ portmapping `8000:8000`. This file does not get loaded when running in CI.
 4. Wait until the container is started and healthy, then attach the debugger.
 
 Again, where `VERSION` is e.g. `70`.
-
-*Protip:* If you get tired of changing the port after every `docker-compose up`, you can temporarily put a
-fixed port in the *docker-compose.yml* of the version you are working with. (The rationale behind using 
-variable ephemeral ports is that during parallel builds on Jenkins port clashes must be avoided.)
-
-For example for version 7.0, change in *apix-docker/70/docker-compose.yml* 
-the ports line from:
-```yaml
-services:
-  alfresco-core:
-    ports:
-      - ${DOCKER_IP}:8080
-``` 
-to: 
-```yaml
-services:
-  alfresco-core:
-    ports:
-      - ${DOCKER_IP}:9070:8080
-```
-and then restart the containers with:
-
-```bash
-./gradlew :apix-docker:docker-70:composeUp --info
-```

apix-docker/70/build.gradle

@@ -1,8 +1,8 @@
 dependencies {
-    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.0.1.3")
+    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.0.1.9")
     baseAlfrescoWar 'org.alfresco:content-services@war'
 }
 
 dockerAlfresco {
-    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.0.1.3'
+    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.0.1.9'
 }

apix-docker/71/build.gradle

@@ -1,8 +1,8 @@
 dependencies {
-    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.1.0")
+    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.1.0.6")
     baseAlfrescoWar 'org.alfresco:content-services@war'
 }
 
 dockerAlfresco {
-    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.1'
+    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.1.0.6'
 }

apix-docker/72/build.gradle

@@ -1,8 +1,8 @@
 dependencies {
-    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.2.0")
+    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.2.1.13")
     baseAlfrescoWar 'org.alfresco:content-services@war'
 }
 
 dockerAlfresco {
-    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.2'
+    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.2.1.13'
 }

apix-docker/73/build.gradle

@@ -1,8 +1,8 @@
 dependencies {
-    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.3.0.1")
+    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.3.1.2")
     baseAlfrescoWar 'org.alfresco:content-services@war'
 }
 
 dockerAlfresco {
-    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.3.0.1'
+    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.3.1.2'
 }

apix-docker/74/build.gradle

@@ -1,8 +1,8 @@
 dependencies {
-    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.4.0.1")
+    baseAlfrescoWar platform("org.alfresco:acs-packaging:7.4.1.3")
     baseAlfrescoWar 'org.alfresco:content-services@war'
 }
 
 dockerAlfresco {
-    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.4.0.1'
+    baseImage = 'private.docker.xenit.eu/alfresco-enterprise/alfresco-repository-enterprise:7.4.1.3'
 }

docs/README.md

@@ -0,0 +1,13 @@
+# Documentation Alfred API
+
+## Generate website
+
+This directory generates the product documentation website at https://docs.xenit.eu/alfred-api/ 
+
+This is done by manually executing:
+```bash
+./build-website.sh
+```
+
+This will generate a ZIP containing the documentation website, which still needs to be
+uploaded and unzipped on our host.

docs/_hugo/config.yaml

@@ -0,0 +1,5 @@
+title: Alfred API
+params:
+  metadata:
+    hugo-config:
+      product: api

docs/build-website.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+set -e
+scriptPath="$( dirname "${BASH_SOURCE[0]}" )" # cd to the directory containing the script
+cd "$scriptPath"
+
+MARKDOWNTOPDF_VERSION=v1.1.4
+MARKDOWNTOWEBSITE_VERSION=1.0.5
+
+MARKDOWNTOPDF_IMAGE="private.docker.xenit.eu/xenit-markdowntopdf:$MARKDOWNTOPDF_VERSION"
+MARKDOWN_SPLITTER_IMAGE="private.docker.xenit.eu/customer/xenit/xenit-manuals-markdown-splitter:$MARKDOWNTOWEBSITE_VERSION"
+MANUALS_HUGO_GENERATOR_IMAGE="private.docker.xenit.eu/customer/xenit/xenit-manuals-hugo-generator:$MARKDOWNTOWEBSITE_VERSION"
+
+WEIGHT=0
+
+build_manual() {
+    echo "===== Building manual ====="
+    local productName="$1"
+    local versionName="$2"
+    shift 2;
+
+    mkdir -p "build/normalized/$productName"
+    tar c --portability -C $versionName . | \
+    docker run --rm -i $MARKDOWNTOPDF_IMAGE --tar \
+    --template default -t markdown-simple_tables-multiline_tables-grid_tables --extract-media assets \
+    --resource-path . \
+    "$@" \
+    -o normalized.md > "build/normalized/$productName/$versionName.tar"
+    sync
+}
+
+split_manual() {
+    echo "===== Splitting manual ====="
+    local productName="$1"
+    local versionName="$2"
+    WEIGHT=$[$WEIGHT + 1]
+    mkdir -p "build/product/$productName"
+    tar tf "build/normalized/$productName/$versionName.tar"
+    cat "build/normalized/$productName/$versionName.tar" | docker run --rm -i $MARKDOWN_SPLITTER_IMAGE normalized.md "target-path=$versionName" "weight=$WEIGHT" > "build/normalized/$productName/$versionName-out.tar"
+    sync
+    tar xf "build/normalized/$productName/$versionName-out.tar" -C "build/product/$productName"
+}
+
+build_and_split_manual() {
+    build_manual "$@"
+    split_manual "$1" "$2"
+}
+
+build_product_website() {
+    echo "===== Building website ====="
+    local productName="$1"
+    mkdir -p "build/website/$productName"
+    cp -r "_hugo" "build/product/$productName/_hugo"
+    tar c --portability -C "build/product/$productName" . | \
+        docker run --rm -i $MANUALS_HUGO_GENERATOR_IMAGE | \
+        tar x -C "build/website/$productName"
+    sync
+}
+
+build_javadoc() {
+    echo "===== Generating javadoc ====="
+    local productName="$1"
+    local alfredapidir=".."
+
+    pushd "$alfredapidir"
+    ./gradlew clean :apix-interface:javadoc
+    popd
+
+    local outputdir="build/website/$productName/"
+    mkdir -p "$outputdir"
+    cp -a "$alfredapidir/apix-interface/build/docs/javadoc" $outputdir
+}
+
+build_swaggerdoc() {
+    echo "===== Copying swaggerdoc ====="
+    local productName="$1"
+    local outputdir="build/website/$productName/"
+
+    mkdir -p $outputdir
+    cp -a "swagger-ui" $outputdir
+}
+
+rm -rf build/
+build_and_split_manual alfred-api user "user-guide.md"
+build_product_website alfred-api
+build_javadoc alfred-api
+build_swaggerdoc alfred-api
+
+find build/website -type f -name '*.html' -print0 | xargs -0 sed -i "/^<\!DOCTYPE html>$/a\
+\<\!-- alfred-docs@$(git describe --always --dirty) --\>"
+
+TODAY=$( date -I )
+tar czf "build/website-alfred-api_$TODAY.tar.gz" -C build/website .

docs/swagger-ui/index.html

@@ -0,0 +1,111 @@
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<!-- alfred-docs@193fb0a-dirty -->
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>Swagger UI</title>
+  <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700"
+    rel="stylesheet">
+  <link rel="stylesheet" type="text/css" href="./swagger-ui.css">
+  <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+  <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+
+    *,
+    *:before,
+    *:after {
+      box-sizing: inherit;
+    }
+
+    body {
+      margin: 0;
+      background: #fafafa;
+    }
+  </style>
+</head>
+
+<body>
+
+  <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="position:absolute;width:0;height:0">
+    <defs>
+      <symbol viewBox="0 0 20 20" id="unlocked">
+        <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
+      </symbol>
+
+      <symbol viewBox="0 0 20 20" id="locked">
+        <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"
+        />
+      </symbol>
+
+      <symbol viewBox="0 0 20 20" id="close">
+        <path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"
+        />
+      </symbol>
+
+      <symbol viewBox="0 0 20 20" id="large-arrow">
+        <path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"
+        />
+      </symbol>
+
+      <symbol viewBox="0 0 20 20" id="large-arrow-down">
+        <path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"
+        />
+      </symbol>
+
+
+      <symbol viewBox="0 0 24 24" id="jump-to">
+        <path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z" />
+      </symbol>
+
+      <symbol viewBox="0 0 24 24" id="expand">
+        <path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z" />
+      </symbol>
+
+    </defs>
+  </svg>
+
+  <div id="swagger-ui"></div>
+
+  <script src="./swagger-ui-bundle.js"> </script>
+  <script src="./swagger-ui-standalone-preset.js"> </script>
+  <script>
+    window.onload = function () {
+
+      var url = window.location.search.match(/url=([^&]+)/);
+      if (url && url.length > 1) {
+        url = decodeURIComponent(url[1]);
+      } else {
+        //url = location.protocol + '//' + location.hostname + (location.port ? ':' + location.port : '') + "/alfresco/s/apix/v1/docs/swagger.json";
+        url = './swagger.json'
+      }
+      console.log("url is...");
+      console.log(url);
+
+      // Build a system
+      const ui = SwaggerUIBundle({
+        url: url,
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+      })
+
+      window.ui = ui
+    }
+  </script>
+</body>
+
+</html>