Merge pull request #62 from dseevr/split_docs

Split RAML into netmaster and auth_proxy routes and combine the HTML output after generation

Author: dseevr

.gitignore

@@ -0,0 +1,3 @@
+# data is extracted from this file and merged into spec/docs/contiv.html as part of the build process
+# but we don't actually need to keep it around.
+spec/docs/auth_proxy.html

scripts/build.sh

@@ -6,32 +6,7 @@ set -euo pipefail
 bash generate.sh
 go install ./ ./client/
 
-# regenerate netmaster.raml
-docker run --rm \
-       -u $(id -u):$(id -g) \
-       -v $(pwd):/files \
-       -w /files/spec \
-       ruby:2.4.0-slim /usr/local/bin/ruby contivModel2raml.rb
-mv spec/netmaster.raml ./spec/contiv/libraries/netmaster.raml
-
-# run the raml2html tool to generate docs under spec/docs
+# update the docs based on the latest code
 pushd spec
 make docs
-mkdir -p docs
-mv contiv.html docs/
 popd
-
-# because we have to do some tidying up of the output HTML and it requires some
-# external dependencies, we use a small Docker image to do it.
-# this image uses the same ruby:2.4.0-slim base as above.
-IMAGE_NAME="contiv_api_documentation_cleanup"
-
-if [[ "$(docker images -q $IMAGE_NAME:latest 2>/dev/null)" == "" ]]; then
-    docker build -t $IMAGE_NAME -f spec/Dockerfile.cleanup .
-fi
-
-docker run --rm \
-       -u $(id -u):$(id -g) \
-       -v $(pwd):/files \
-       -w /files/spec \
-       $IMAGE_NAME /usr/local/bin/ruby cleanup.rb

spec/Dockerfile

@@ -2,10 +2,8 @@ FROM node:alpine
 
 RUN npm install -g raml2html
 
-COPY . /contiv
+RUN mkdir /contiv
 
 WORKDIR /contiv
 
-RUN raml2html -i contiv.raml -o contiv.html
-
-ENTRYPOINT ["/bin/sh"]
+ENTRYPOINT ["raml2html"]

spec/Makefile

@@ -1,6 +1,6 @@
 all: docs
 
 docs:
-	@./build.sh
+	@bash ./build.sh
 
 .PHONY: docs

spec/auth_proxy.raml

@@ -0,0 +1,97 @@
+#%RAML 1.0
+title: Contiv
+description: Contiv API Specification
+version: v1
+baseUri:
+  value: https://{serverfqdn}:10000/api/{version}
+  (rediractable): true
+baseUriParameters:
+  serverfqdn:
+    type: string
+protocols: [  HTTPS ]
+mediaType: [ application/json ]
+
+resourceTypes:
+  collection: !include auth_proxy/schemas/collection.raml
+  non-upd-collection-item: !include auth_proxy/schemas/non-upd-collection-item.raml
+  collection-item: !include auth_proxy/schemas/collection-item.raml
+  ro-collection-item: !include auth_proxy/schemas/ro-collection-item.raml
+
+annotationTypes:
+  info:
+    properties:
+      license:
+        type: string
+        enum: [ "Apache 2.0" ]
+    allowedTargets: API
+  rediractable: boolean
+
+securitySchemes:
+  custom_scheme: !include auth_proxy/schemas/custom-scheme.raml
+
+# Resource templates
+uses:
+  auth_proxy: auth_proxy/libraries/auth_proxy.raml
+
+securedBy: custom_scheme
+
+# auth_proxy endpoints
+/auth_proxy:
+  displayName: Auth API
+  description: Authentication/Authorization related API
+
+  /health:
+    get:
+      securedBy: [ null ]
+      responses:
+        200:
+          body:
+            application/json:
+              type: auth_proxy.health
+
+  /login:
+    post:
+      description: Login to Contiv API server
+      securedBy: [ null ]
+      body:
+        application/json:
+          type: auth_proxy.login
+      responses:
+        200:
+          body:
+            application/json:
+              type: auth_proxy.login_response
+        400:
+        401:
+
+  /version:
+    get:
+      securedBy: [ null ]
+      responses:
+        200:
+          body:
+            application/json: |
+              { "version": "1.0.0-beta" }
+
+  /authorizations:
+    type: {collection: {provider: auth_proxy}}
+    displayName: Authorizations
+
+    /{authzUUID}:
+      type: {non-upd-collection-item: {provider: auth_proxy}}
+      displayName: Authorization
+
+  /local_users:
+    type: {collection: {provider: auth_proxy}}
+    displayName: Local Users
+
+    /{username}:
+      type: {collection-item: {provider: auth_proxy}}
+      displayName: Local User
+      patch:
+
+  /ldap_configuration:
+    type: {collection-item: {provider: auth_proxy}}
+    displayName: LDAP Configuration
+    put:
+    patch:

spec/contiv/libraries/auth_proxy.raml spec/auth_proxy/libraries/auth_proxy.raml

@@ -0,0 +1,32 @@
+#%RAML 1.0 ResourceType
+description: Entity representing <<resourcePathName|!singularize>>
+get:
+  description: returns <<resourcePathName|!singularize>>.
+  responses:
+    200:
+      body:
+        application/json:
+          type: <<provider>>.<<resourcePathName|!singularize>>
+    404:
+      body:
+        application/json: |
+          {"message": "<<resourcePathName|!singularize>> not found" }
+delete:
+  description: deletes <<resourcePathName|!singularize>>.
+  responses:
+    204:
+put?:
+  description: updates/creates <<resourcePathName|!singularize>>
+  body:
+    application/json: 
+      type: <<provider>>.upd_<<resourcePathName|!singularize>>
+  responses:
+    200:
+      body:
+        application/json:
+          type: <<provider>>.<<resourcePathName|!singularize>>
+    404:
+      body:
+        application/json: |
+          {"message": "<<resourcePathName|!singularize>> not found" }
+

spec/auth_proxy/schemas/collection-item.raml

@@ -0,0 +1,17 @@
+#%RAML 1.0 ResourceType
+description: A collection of <<resourcePathName>>
+get:
+  description: returns a list of <<resourcePathName|!singularize>>.
+  responses:
+    200:
+      body:
+        application/json:
+          type: <<provider>>.<<resourcePathName>>
+post:
+  description: Add a new <<resourcePathName|!singularize>>.
+  body:
+    application/json:
+      type: <<provider>>.<<resourcePathName|!singularize>>
+  responses:
+    201:
+    404:

spec/auth_proxy/schemas/collection.raml

@@ -2,7 +2,52 @@
 
 set -euo pipefail
 
-docker build -t contiv/spec .
-cid=$(docker run -itd contiv/spec)
-docker cp ${cid}:/contiv/contiv.html .
-docker rm -fv ${cid}
+mkdir -p docs
+
+#
+# regenerate libraries/netmaster.raml which holds the type netmaster type data
+#
+docker run --rm \
+       -u $(id -u):$(id -g) \
+       -v $(pwd)/../:/files \
+       -w /files/spec \
+       ruby:2.4.0-slim /usr/local/bin/ruby generate_raml.rb ./netmaster/libraries/netmaster.raml
+
+#
+# convert the raml into HTML output
+#
+RAML_IMAGE_NAME="contiv/raml2html"
+
+if [[ "$(docker images -q $RAML_IMAGE_NAME:latest 2>/dev/null)" == "" ]]; then
+    docker build -t $RAML_IMAGE_NAME .
+fi
+
+echo "generating netmaster docs"
+docker run --rm \
+       -u $(id -u):$(id -g) \
+       -v $(pwd):/contiv \
+       $RAML_IMAGE_NAME -i netmaster.raml -o docs/contiv.html
+
+echo "generating auth_proxy docs"
+docker run --rm \
+       -u $(id -u):$(id -g) \
+       -v $(pwd):/contiv \
+       $RAML_IMAGE_NAME -i auth_proxy.raml -o docs/auth_proxy.html
+
+#
+# because we have to do some tidying up of the output HTML and it requires some
+# external dependencies, we use a small Docker image to do it.
+# this image uses the same ruby:2.4.0-slim base as above.
+#
+CLEANUP_IMAGE_NAME="contiv/api_documentation_cleanup"
+
+if [[ "$(docker images -q $CLEANUP_IMAGE_NAME:latest 2>/dev/null)" == "" ]]; then
+    docker build -t $CLEANUP_IMAGE_NAME -f Dockerfile.cleanup .
+fi
+
+echo "Cleaning up HTML output"
+docker run --rm \
+       -u $(id -u):$(id -g) \
+       -v $(pwd):/files \
+       -w /files \
+       $CLEANUP_IMAGE_NAME /usr/local/bin/ruby cleanup.rb

spec/contiv/schemas/custom-scheme.raml spec/auth_proxy/schemas/custom-scheme.raml

@@ -7,8 +7,23 @@
 
 doc = Nokogiri::HTML(File.read(FILENAME))
 
-# add trailing slashes to all paths
+# ----- IMPORT AUTH_PROXY DATA ----------------------------------------------------------------------
+
+auth_doc = Nokogiri::HTML(File.read("docs/auth_proxy.html"))
+
+# extract the main panel and sidebar link nodes
+auth_panel = auth_doc.css(".panel-default").first
+sidebar_link = auth_doc.css("#sidebar ul li").first
+
+# add auth_proxy api panel under the header
+doc.at(".page-header").after(auth_panel)
+
+# add auth_proxy link to the top of the sidebar
+doc.at("#sidebar ul").prepend_child(sidebar_link)
+
+# ----- TIDY OUTPUT FILE ----------------------------------------------------------------------------
 
+# add trailing slashes to all paths
 node_groups = [
   doc.css(".panel-title a").select { |n| n.text.start_with?("/") },
   doc.css(".modal-title"),
@@ -19,13 +34,12 @@
 end
 
 # insert additional <head> tag requirements for the contiv header
-
 doc.at("head") << Nokogiri::HTML::DocumentFragment.parse(File.read("docs/head.html"))
 
 # insert the contiv header html into the top of the <body>
-
 doc.at("body").prepend_child(Nokogiri::HTML::DocumentFragment.parse(File.read("docs/body.html")))
 
-# overwrite the original HTML file
+# ----- OUTPUT --------------------------------------------------------------------------------------
 
+# overwrite the original HTML file
 File.write(FILENAME, doc.to_html)