Add swagger gh pages generation, badges and links to the README (#1001)

* Ignore ApiSpec module coverage

* Add swagger ui generation step to the CI

* Allow generating swagger ui if no endpoint was started

* Add documentation links, badges to README; remove ToC and fix grammar

* Update coverall.json config

.github/workflows/ci.yaml

@@ -126,6 +126,13 @@ jobs:
           key: ${{ runner.os }}-${{ env.OTP_VERSION }}-${{ env.ELIXIR_VERSION }}-${{ hashFiles('mix.lock') }}
       - name: Build docs
         uses: lee-dohm/generate-elixir-docs@v1
+      - name: Generate openapi.json
+        run: mix openapi.spec.json --start-app=false --spec TrentoWeb.OpenApi.ApiSpec
+      - name: Generate Swagger UI
+        uses: Legion2/swagger-ui-action@v1
+        with:
+          output: ./doc/swaggerui
+          spec-file: openapi.json
       - name: Publish to Pages
         uses: peaceiris/actions-gh-pages@v3
         with:

README.md

@@ -1,90 +1,89 @@
 # Trento
 
-An open cloud-native web console improving on the work day of SAP Applications administrators.
+[![CI](https://github.com/trento-project/web/actions/workflows/ci.yaml/badge.svg)](https://github.com/trento-project/web/actions/workflows/ci.yaml)
+[![Coverage Status](https://coveralls.io/repos/github/trento-project/web/badge.svg?branch=main)](https://coveralls.io/github/trento-project/web?branch=main)
+[![Documentation](https://img.shields.io/badge/documentation-grey.svg)](https://trento-project.io/web/)
 
-# Table of contents
+An open cloud-native web console aiming to improve the workday of SAP Applications administrators.
 
-- [Introduction](#introduction)
-- [Features](#features)
-  - [Automated discovery](#sap-hana-ha-automated-discovery)
-  - [Reactive Control Plane](#reactive-control-plane)
-  - [Configuration validation](#configuration-validation)
-  - [Monitoring](#monitoring)
-  - [Alerting](#alerting)
-- [Installation](#installation)
-- [Support](#support)
-- [Contributing](#contributing)
-- [License](#license)
+# Documentation
 
-# Introduction
+The documentation is available at [trento-project.io/web](https://trento-project.io/web/).
+
+Swagger UI is available at [trento-project.io/web/swaggerui](https://trento-project.io/web/swaggerui).
+
+# Overview
 
 _Trento_ is a comprehensive cloud-native, distributed monitoring solution.
 
-It's made by three main components:
+It's made of three main components:
 
 - Trento Agent
 - Trento Runner
 - Trento Web (current repository)
 
 [Trento Agent](https://github.com/trento-project/agent) is a single background **process running in each host of the target** infrastructure the user desires to monitor.
-
-[Trento Runner](https://github.com/trento-project/runner) responsible of **running the Trento configuration health checks** among the installed Trento Agents.
+[Trento Runner](https://github.com/trento-project/runner) is responsible for **running** the Trento configuration health checks\*\* among the installed Trento Agents.
 
 _Trento Web_ is the **control plane of the Trento Platform**.
-In cooperation with the Agents and the Runner discovers, observes, monitors and checks the target SAP infrastructure.
+In cooperation with the Agents and the Runner it discovers, observes, monitors and checks the target SAP infrastructure.
 
 See the [architecture document](./guides/architecture/trento-architecture.md) for additional details.
 
 > Being the project in development, all of the above might be subject to change!
 
 # Features
+
 ## SAP HANA HA Automated discovery
 
-The central server integrates with the Agents discoveries by **collecting** information about the target SAP infrastructure and then **detects** different kind of scenarios and **reacts** accordingly.
+The central server integrates with the agents discoveries by **collecting** information about the target SAP infrastructure and then **detects** different kinds of scenarios and **reacts** accordingly.
 
 See also [Trento Agent](https://github.com/trento-project/agent) for additional information.
+
 ## Reactive Control Plane
 
-By leveraging modern approaches to software architecture and engineering and top notch technologies we built a **reactive system** that provides **realtime** feedbacks about the **changes in the target** infrastructure.
+By leveraging modern approaches to software architecture and engineering and top-notch technologies we built a **reactive system** that provides **real-time** feedback about the **changes in the target** infrastructure.
 
 Here's a non-comprehensive list of the capabilities provided by the bundled Web UI:
 
 - Global Health Overview
 - Hosts Overview and Detail
 - Pacemaker Clusters Overview and Detail
 - SAP Systems Overview and Detail
-- HANA Databases Overview and Detail 
+- HANA Databases Overview and Detail
 - Checks Catalog
+
 ## Configuration validation
 
-Trento is able to execute a variety of *configuration health checks* (a.k.a. the _HA Config Checks_) among the installed Trento Agents.
+Trento is able to execute a variety of _configuration health checks_ (a.k.a. the _HA Config Checks_) among the installed Trento Agents.
 
 - Pacemaker, Corosync, SBD, SAPHanaSR and other generic _SUSE Linux Enterprise for SAP Application_ OS settings
 - Specific configuration audits for SAP HANA Scale-Up Performance-Optimized scenarios deployed on MS Azure cloud.
 
 See [Trento Runner](https://github.com/trento-project/runner) for additional information.
 
 ## Monitoring
-It is important in critycal business systems to have access to relevant information about _how things are going_.
 
-Currently Trento provides a basic integration with **Grafana** and **Prometheus**.
+It is important in critical business systems to have access to relevant information about _how things are going_.
+Currently, Trento provides basic integration with **Grafana** and **Prometheus**.
 
 See [related documentation](./guides/monitoring/monitoring.md) for more information.
 
 ## Alerting
-Alerting feature notifies the SAP Administrator about important updated in the Landscape being monitored/observed by Trento.
+
+Alerting feature notifies the SAP Administrator about important updates in the Landscape being monitored/observed by Trento.
 
 See [related documentation](./guides/alerting/alerting.md) for more information.
 
 # Installation
 
 _Trento_ is intended to run in many ways, depending on needs, and also the different components have their own requirements and constraints.
 
-Please check the specific [Agent](https://github.com/trento-project/agent) and [Runner](https://github.com/trento-project/runner) documentations for respective details.
+Please check the specific [Agent](https://github.com/trento-project/agent) and [Runner](https://github.com/trento-project/runner) documentation for respective details.
 
 If you intend to install Trento on a k8s cluster, you may be interested in our [helm-charts](https://github.com/trento-project/helm-charts) repo for detailed instructions.
 
-If otherwise you want to play around with the current repository, go ahead,  [hack on the trento](./guides/development/hack_on_the_trento.md) and **have a lot of fun**!
+If otherwise you want to play around with the current repository, go ahead, [hack on the trento](./guides/development/hack_on_the_trento.md) and **have a lot of fun**!
 
 # Support
 
@@ -108,4 +107,4 @@ https://www.apache.org/licenses/LICENSE-2.0
 Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
-specific language governing permissions and limitations under the License.
+specific language governing permissions and limitations under the License.

coveralls.json

@@ -1,3 +1,12 @@
 {
-  "skip_files": ["test/support"]
+  "skip_files": [
+    "test/support",
+    "lib/trento_web.ex",
+    "lib/trento_web/endpoint.ex",
+    "lib/trento_web/router.ex",
+    "lib/trento_web/openapi/api_spec.ex",
+    "lib/trento_web/telemetry.ex",
+    "lib/trento_web/error_helpers.ex"
+  ],
+  "treat_no_relevant_lines_as_covered": true
 }

lib/trento_web/openapi/api_spec.ex

@@ -11,8 +11,7 @@ defmodule TrentoWeb.OpenApi.ApiSpec do
   def spec do
     OpenApiSpex.resolve_schema_modules(%OpenApi{
       servers: [
-        # Populate the Server info from a phoenix endpoint
-        Server.from_endpoint(Endpoint)
+        endpoint()
       ],
       info: %Info{
         title: "Trento",
@@ -37,4 +36,16 @@ defmodule TrentoWeb.OpenApi.ApiSpec do
       ]
     })
   end
+
+  defp endpoint do
+    if Process.whereis(Endpoint) do
+      # Populate the Server info from a phoenix endpoint
+      Server.from_endpoint(Endpoint)
+    else
+      # If the endpoint is not running, use a placeholder
+      # this happens when generarting openapi.json with --start-app=false
+      # e.g. mix openapi.spec.json --start-app=false --spec WandaWeb.ApiSpec
+      %OpenApiSpex.Server{url: "https://demo.trento-project.io"}
+    end
+  end
 end