Documentation

Issue-ID: AAF-1091
Signed-off-by: Zebek Bogumil <bogumil.zebek@nokia.com>
Change-Id: I59df0545c4dd5adfde32c83988f89cd2d0c4676b

15 files changed, 440 insertions, 5 deletions

diff --git a/certService/README.md b/certService/README.md
index 8e7fccc4..61506e79 100644
--- a/certService/README.md
+++ b/certService/README.md
@@ -88,11 +88,11 @@ path:
 cd /var/log/onap/aaf/certservice
 ```
 You should see:    
-audit.log  error.log  trace.log
+audit.log  error.log  debug.log
 
 ### RestAPI
 API is described by Swagger ( OpenAPI 3.0 ) on endpoint /docs 
 ( endpoint is defined in properties as springdoc.swagger-ui.path )
 ```
 http://localchost:8080/docs
-```
\ No newline at end of file
+```
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 00000000..65513dc3
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+clean:
+	@echo "##### Clean build directory #####"
+	rm -rf $(BUILDDIR)
+	@echo "##### Done #####"
+
+.PHONY: help clean Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..15deadea
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,21 @@
+## AAF Certification Service documentation
+###Requirements
+    Python 3.x
+
+To generate a documentation locally follow below steps.
+
+1. Open **docs** folder in terminal
+2. Install all required dependencies
+
+    ```
+    python install -r requirements-docs.txt
+   ```
+3. Generate local documentation
+    ```
+    make html
+    ```
+    After command execution the documentation will be available in **_build/html** folder.
+4. Before you commit documentation changes please execute
+    ```
+    make clean
+   ```
diff --git a/docs/conf.py b/docs/conf.py
index 8f40e8b8..b37b90cf 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -7,6 +7,9 @@ linkcheck_ignore = [
     'http://localhost',
 ]
 
+extensions = [
+    'sphinxcontrib.openapi',
+]
 intersphinx_mapping = {}
 
 html_last_updated_fmt = '%d-%b-%y %H:%M'
diff --git a/docs/index.rst b/docs/index.rst
index 87b61527..e84df935 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,7 +2,22 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. Copyright 2020 NOKIA
 
-AAF Cert Service
-------------------------------------------------
+AAF Certification Service
+=========================================
+
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
+   :caption: Contents:
+
+   sections/architecture.rst
+   sections/build.rst
+   sections/offeredapis.rst
+   sections/logging.rst
+   sections/installation.rst
+   sections/configuration.rst
+   sections/release-notes.rst
+
+Indices and tables
+==================
+
+* :ref:`search`
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index b3188ddd..98fc25ce 100644
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -10,6 +10,7 @@ sphinxcontrib-needs>=0.2.3
 sphinxcontrib-nwdiag
 sphinxcontrib-seqdiag
 sphinxcontrib-swaggerdoc
+sphinxcontrib-openapi
 sphinxcontrib-plantuml
 sphinx_bootstrap_theme
 lfdocs-conf
diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst
new file mode 100644
index 00000000..654208d1
--- /dev/null
+++ b/docs/sections/architecture.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Architecture
+============
+
+The micro-service called CertService is designed for requesting certificates
+signed by external Certificate Authority (CA) using CMP over HTTP protocol. It uses CMPv2 client to send and receive CMPv2 messages.
+CertService's client will be also provided so other ONAP components (aka end components) can easily get certificate from CertService.
+End component is an ONAP component (e.g. DCAE collector or controller) which requires certificate from CMPv2 server
+to protect external traffic and uses CertService's client to get it.
+CertService's client communicates with CertService via REST API over HTTPS, while CertService with CMPv2 server via CMP over HTTP.
+
+.. image:: img/certservice_high_level.jpg
+   :width: 855px
+   :height: 178px
+   :alt: Interaction between components
diff --git a/docs/sections/build.rst b/docs/sections/build.rst
new file mode 100644
index 00000000..d533e330
--- /dev/null
+++ b/docs/sections/build.rst
@@ -0,0 +1,61 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Build
+=====
+
+Jenkins
+-------
+#. JJB Master
+
+    https://jenkins.onap.org/view/aaf/job/aaf-certservice-master-merge-java/
+
+#. JJB Stage
+
+    https://jenkins.onap.org/view/aaf/job/aaf-certservice-maven-docker-stage-master/
+
+#. JJB Release
+
+    https://jenkins.onap.org/view/aaf/job/aaf-certservice-maven-stage-master/
+    https://jenkins.onap.org/view/aaf/job/aaf-certservice-release-merge/
+
+#. JJB CSIT
+
+    https://jenkins.onap.org/view/CSIT/job/aaf-master-csit-certservice/
+
+Environment
+-----------
+
+* Java 11
+* Apache Maven 3.6.0
+* Linux
+* Docker 18.09.5
+* Python 2.7.x
+
+How to build images?
+--------------------
+
+#. Checkout the project from https://gerrit.onap.org/r/#/admin/projects/aaf/certservice
+#. Read information's stored in README.md file
+#. Use a Makefile to build images::
+
+    make build
+
+How to start service locally?
+-----------------------------------------------
+#. Start Cert Service with configured EJBCA::
+
+    make start-backend
+
+#. Run Cert Service Client::
+
+    make run-client
+
+#. Remove client container::
+
+    make stop-client
+
+#. Stop Cert Service and EJBCA::
+
+    make stop-backend
diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
new file mode 100644
index 00000000..47f2dd87
--- /dev/null
+++ b/docs/sections/configuration.rst
@@ -0,0 +1,28 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Configuration
+=============
+
+.. note::
+   * This section is used to describe the options a software component offers for configuration.
+
+   * Configuration is typically: provided for platform-component and sdk projects;
+     and referenced in developer and user guides.
+   
+   * This note must be removed after content has been added.
+
+
+
+Example ...
+
+You can provide the following in ``basic.conf``
+
+``host=ADDRESS``
+  The address of the host
+
+``port=PORT``
+  The port used for signaling
+
+  Optional. Default: ``8080``
diff --git a/docs/sections/img/certservice_high_level.jpg b/docs/sections/img/certservice_high_level.jpg
new file mode 100644
index 00000000..11466983
--- /dev/null
+++ b/docs/sections/img/certservice_high_level.jpg
diff --git a/docs/sections/installation.rst b/docs/sections/installation.rst
new file mode 100644
index 00000000..8ef137fc
--- /dev/null
+++ b/docs/sections/installation.rst
@@ -0,0 +1,21 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Installation
+============
+
+.. note::
+   * This section is used to describe how a software component is acquired and installed.
+   
+   * This section is typically: provided for a platform-component and application; and
+     referenced in user guides.
+
+   * This note must be removed after content has been added.
+
+Environment
+-----------
+
+
+Steps
+-----
diff --git a/docs/sections/logging.rst b/docs/sections/logging.rst
new file mode 100644
index 00000000..159b5132
--- /dev/null
+++ b/docs/sections/logging.rst
@@ -0,0 +1,25 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Logging
+=======
+
+Where to Access Information
+---------------------------
+
+Certification Service logs are available in the Docker container
+
+    docker exec -it aaf-certservice-api bash
+
+Path to logs:
+
+    /var/log/onap/aaf/certservice
+
+Available log files:
+
+    * audit.log
+    * debug.log
+    * error.log
+
+
diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
new file mode 100644
index 00000000..fe5807a8
--- /dev/null
+++ b/docs/sections/offeredapis.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Offered APIs
+============
+
+AAF Cert Service Api
+--------------------
+
+.. openapi:: ../../certService/OpenAPI.yaml
diff --git a/docs/sections/openapi.yaml b/docs/sections/openapi.yaml
new file mode 100644
index 00000000..cee5a402
--- /dev/null
+++ b/docs/sections/openapi.yaml
@@ -0,0 +1,158 @@
+openapi: 3.0.1
+info:
+  title: CertService Documentation
+  description: Certification service API documentation
+  version: 1.0.0
+servers:
+  - url: http://localhost:8080
+    description: Generated server url
+tags:
+  - name: Actuator
+    description: Monitor and interact
+    externalDocs:
+      description: Spring Boot Actuator Web API Documentation
+      url: https://docs.spring.io/spring-boot/docs/current/actuator-api/html/
+paths:
+  /v1/certificate/{caName}:
+    get:
+      tags:
+        - CertificationService
+      summary: sign certificate
+      description: Web endpoint for requesting certificate signing. Used by system
+        components to gain certificate signed by CA.
+      operationId: signCertificate
+      parameters:
+        - name: caName
+          in: path
+          description: Name of certification authority that will sign CSR.
+          required: true
+          schema:
+            type: string
+        - name: CSR
+          in: header
+          description: Certificate signing request in form of PEM object encoded in
+            Base64 (with header and footer).
+          required: true
+          schema:
+            type: string
+        - name: PK
+          in: header
+          description: Private key in form of PEM object encoded in Base64 (with header
+            and footer).
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: certificate successfully signed
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/CertificationModel'
+        "500":
+          description: something went wrong during connecting to cmp client
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/ErrorResponseModel'
+        "404":
+          description: CA not found for given name
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/ErrorResponseModel'
+        "400":
+          description: given CSR or/and PK is incorrect
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/ErrorResponseModel'
+  /ready:
+    get:
+      tags:
+        - CertificationService
+      summary: check is container is ready
+      description: Web endpoint for checking if service is ready to be used.
+      operationId: checkReady
+      responses:
+        "200":
+          description: configuration is loaded and service is ready to use
+          content:
+            application/json; charset=utf-8:
+              schema:
+                type: string
+        "503":
+          description: configuration loading failed and service is unavailable
+          content:
+            application/json; charset=utf-8:
+              schema:
+                type: string
+  /reload:
+    get:
+      tags:
+        - CertificationService
+      summary: reload service configuration from file
+      description: Web endpoint for performing configuration reload. Used to reload
+        configuration file from file.
+      operationId: reloadConfiguration
+      responses:
+        "200":
+          description: configuration has been successfully reloaded
+          content:
+            application/json; charset=utf-8:
+              schema:
+                type: string
+        "500":
+          description: something went wrong during configuration loading
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/ErrorResponseModel'
+  /actuator/health:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator web endpoint 'health'
+      operationId: handle_0
+      responses:
+        "200":
+          description: default response
+          content: {}
+  /actuator/health/**:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator web endpoint 'health-path'
+      operationId: handle_1
+      responses:
+        "200":
+          description: default response
+          content: {}
+  /actuator:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator root web endpoint
+      operationId: links_2
+      responses:
+        "200":
+          description: default response
+          content: {}
+components:
+  schemas:
+    ErrorResponseModel:
+      type: object
+      properties:
+        errorMessage:
+          type: string
+    CertificationModel:
+      type: object
+      properties:
+        certificateChain:
+          type: array
+          items:
+            type: string
+        trustedCertificates:
+          type: array
+          items:
+            type: string
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
new file mode 100644
index 00000000..bd00ac74
--- /dev/null
+++ b/docs/sections/release-notes.rst
@@ -0,0 +1,50 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+
+Release Notes
+=============
+
+Version: 1.0.0
+--------------
+
+:Release Date: 2020-03-25
+
+**New Features**
+
+The Frankfurt Release is the first release of the Certification Service.
+
+**Bug Fixes**
+
+        - No new fixes were implemented for this release
+
+**Known Issues**
+
+        N/A
+
+**Security Notes**
+
+        N/A
+
+*Fixed Security Issues*
+
+        N/A
+
+*Known Security Issues*
+
+        N/A
+
+*Known Vulnerabilities in Used Modules*
+
+        N/A
+
+**Upgrade Notes**
+
+**Deprecation Notes**
+
+**Other**
+
+===========
+
+End of Release Notes