Add a transformer to generate a page for Swagger

1 year ago · dc7dba6c38
parent 5b5f58513f
commit dc7dba6c38
5 changed files with 163 additions and 21 deletions
--- a/2
+++ b/2
@ -1,7 +1,7 @@
 FROM alpine:3.18
 LABEL author="Maxime Batista"

-RUN apk add --no-cache bash openssh-client rsync
+RUN apk add --no-cache openssh-client rsync
 RUN --mount=type=secret,id=ssh_private_key \
  mkdir -m 700 /root/.ssh && \
  cp /run/secrets/ssh_private_key /root/.ssh/id_rsa && \
--- a/README.md
+++ b/README.md
@ -17,6 +17,8 @@ steps:
    image: corentinaltepe/doxygen:latest
    commands:
      - cd code
+# Uncomment to generate a Doxyfile in the pipeline if not committed in the repository.
+#      - doxygen -s -g && sed -i 's/RECURSIVE              = NO/RECURSIVE              = YES/' Doxyfile
      - doxygen

  - name: deploy-docs
@ -31,3 +33,62 @@ steps:
        - master
        - main
 ```
+
+### Swagger
+
+```yml
+kind: pipeline
+name: default
+
+steps:
+  - name: deploy-swagger
+    image: hub.codefirst.iut.uca.fr/maxime.batista/codefirst-docdeployer:0.2
+    settings:
+      source: ./target/openapi.yaml
+      target: api-docs
+      transform: swagger
+    failure: ignore
+# You may depend on a previous step that generate the OpenAPI definition file
+#    depends_on: [build-openapi]
+    when:
+      branch:
+        - master
+        - main
+```
+
+### JavaDoc
+
+```yml
+kind: pipeline
+name: default
+
+steps:
+  - name: build-javadoc
+    image: maven:3-eclipse-temurin-17-alpine
+    commands:
+      - mvn javadoc:javadoc
+
+  - name: deploy-javadoc
+    image: hub.codefirst.iut.uca.fr/maxime.batista/codefirst-docdeployer:0.2
+    settings:
+      source: ./target/site/apidocs
+      target: javadoc
+    failure: ignore
+    depends_on: [build-javadoc]
+    when:
+      branch:
+        - master
+        - main
+```
+
+## Configuration
+
+This image is designed to be used a Drone plugin. It can be configured using the following parameters:
+
+| Parameter | Description |
+| --------- | ----------- |
+| `source` | The directory* containing the files to deploy. |
+| `target` | The target directory to deploy the documentation to. |
+| `transform` | The transformation to apply to the documentation. Can be `none` (default), `swagger`. |
+
+*If using the `swagger` transformation, the `source` parameter must be the path to the OpenAPI definition **file**.
--- a/entrypoint.sh
+++ b/entrypoint.sh
@ -1,17 +1,69 @@
-#!/usr/bin/env bash
+#!/usr/bin/env sh

-set -eu
-
-if [ ! -e "${PLUGIN_SOURCE:-}" ]; then
-  echo 'Specify at least one source!' >&2
+error() {
+  echo "$*" >&2
  exit 1
+}
+
+if [ -z "$PLUGIN_SOURCE" ]; then
+  error 'Specify at least one source!'
 fi

-if [ -z "${PLUGIN_TARGET:-}" ]; then
-  echo 'Specify a target!' >&2
-  exit 1
+if [ ! -e "$PLUGIN_SOURCE" ]; then
+  error "'$PLUGIN_SOURCE' does not exist!"
+fi
+
+if [ -z "$PLUGIN_TARGET" ]; then
+  error 'Specify a target directory!'
+fi
+
+if [ -n "$PLUGIN_TRANSFORM" ]; then
+  case "$PLUGIN_TRANSFORM" in
+    'swagger')
+      [ -r "$PLUGIN_SOURCE" ] || error "$PLUGIN_SOURCE is not a readable regular file."
+      openapi="$(basename -- "$PLUGIN_SOURCE")"
+      mkdir -p /tmp/swagger-gen
+      cp "$PLUGIN_SOURCE" "/tmp/swagger-gen/$openapi"
+      cat > /tmp/swagger-gen/index.html <<HTML
+<!DOCTYPE html>
+<html lang="en">
+  <head><meta charset="utf-8"><title>Swagger UI</title><link rel="stylesheet" href="/swagger-ui.css"></head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="/swagger-ui-bundle.js"></script>
+    <script src="/swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.onload = function() {
+        window.ui = SwaggerUIBundle({
+          url: "$openapi",
+          dom_id: "#swagger-ui",
+          deepLinking: true,
+          presets: [
+            SwaggerUIBundle.presets.apis,
+            SwaggerUIStandalonePreset
+          ],
+          plugins: [
+            SwaggerUIBundle.plugins.DownloadUrl
+          ],
+          layout: "StandaloneLayout"
+        })
+      };
+    </script>
+  </body>
+</html>
+HTML
+      PLUGIN_SOURCE=/tmp/swagger-gen
+      ;;
+    none)
+      ;;
+    *)
+      error "Unknown '$PLUGIN_TRANSFORM' transform!"
+      ;;
+  esac
 fi

+set -euo pipefail
+
 echo "Repository name : $DRONE_REPO_NAME"
 echo "Repository owner: $DRONE_REPO_OWNER"

--- a/test/nginx/Dockerfile
+++ b/test/nginx/Dockerfile
@ -1,3 +1,3 @@
-FROM linuxserver/openssh-server:9.1_p1-r3-ls115
+FROM linuxserver/openssh-server:9.3_p2-r0-ls129

 RUN apk add --no-cache rsync
--- a/test/test_image.sh
+++ b/test/test_image.sh
@ -1,6 +1,6 @@
 #!/bin/bash

-set -eu
+set -u

 declare -g EXPECTED_DOC_BASE_PATH='/usr/share/nginx/html/octocat/hello-world'
 declare -g VERBOSE='false'
@ -18,12 +18,10 @@ run_image() {
  # named 'nginx'. The codefirst-nginx container acts as a SSH server and will
  # be started and stopped automatically. The SSH user, port and authorized
  # keys are already configured.
-  local branch=$1
-  local image=$2
-  local source=$3
-  local target=$4
+  local branch="$1"
+  local image="$2"
  local pubkey=$(<"$root_dir/id_rsa.pub")
-  shift 4
+  shift 2
  docker network inspect codefirst &> /dev/null || docker network create codefirst
  nginx_id=$(docker run --rm -d -v codefirst-nginx:/usr/share/nginx --net=codefirst -e PUBLIC_KEY="$pubkey" -e USER_NAME=codefirst -e PUID=0 --hostname=nginx codefirst-nginx)
  sleep 2 # Wait to let the container start
@ -31,17 +29,18 @@ run_image() {
    --net=codefirst \
    --entrypoint '/bin/sh' \
    --workdir /drone/src \
-    --rm $image \
+    --rm "$image" \
    -c "$*"
  docker run -v codefirst-docdeployer-drone:/drone/src \
    --net=codefirst \
    -e DRONE_REPO_NAME=hello-world \
    -e DRONE_REPO_OWNER=octocat \
    -e DRONE_REPO=octocat/hello-world \
-    -e DRONE_BRANCH=$branch \
+    -e "DRONE_BRANCH=$branch" \
    -e DRONE_COMMIT=7fd1a60b01f91b314f59955a4e4d4e80d8edf11d \
-    -e PLUGIN_SOURCE=$source \
-    -e PLUGIN_TARGET=$target \
+    -e "PLUGIN_SOURCE=${plugin[source]}" \
+    -e "PLUGIN_TARGET=${plugin[target]}" \
+    -e "PLUGIN_TRANSFORM=${plugin[transform]:-none}" \
    --entrypoint '/bin/sh' \
    --workdir /drone/src \
    --rm codefirst-docdeployer \
@ -93,9 +92,39 @@ docker build -t codefirst-docdeployer --secret id=ssh_private_key,src="$root_dir
 docker build -t codefirst-nginx "$root_dir/test/nginx"

 test_deploy() {
-  run_image master corentinaltepe/doxygen html code-doc 'doxygen -s -g && doxygen'
+  declare -A plugin=(
+    [source]='html'
+    [target]='code-doc'
+  )
+  run_image master corentinaltepe/doxygen 'doxygen -s -g && doxygen'
  assert_file_exists 'code-doc/index.html'
  cleanup
 }

+test_swagger() {
+  declare -A plugin=(
+    [source]='target/swagger.json'
+    [target]='api-def'
+    [transform]='swagger'
+  )
+  run_image main busybox 'mkdir target && echo "{}" > target/swagger.json'
+  assert_file_exists api-def/index.html
+  assert_file_exists api-def/swagger.json
+  assert_file_contains api-def/index.html 'swagger.json'
+  cleanup
+}
+
+test_javadoc() {
+  declare -A plugin=(
+    [source]='./docdeployer/target/site/apidocs'
+    [target]='javadoc'
+  )
+  run_image main maven:3-eclipse-temurin-17-alpine 'mvn archetype:generate -q -DgroupId=fr.uca.iut.codefirst -DartifactId=docdeployer -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false && cd docdeployer && mvn javadoc:javadoc -q'
+  assert_file_exists javadoc/index.html
+  assert_file_exists javadoc/fr/uca/iut/codefirst/App.html
+  cleanup
+}
+
 test_deploy
+test_swagger
+test_javadoc