From 5ffefffcdf2d136a59241c737cea9a276f407094 Mon Sep 17 00:00:00 2001
From: lcampos <luis@zuplo.com>
Date: Mon, 29 Jul 2024 18:56:38 -0700
Subject: [PATCH] update readme (#15)

---
 README.md | 92 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 71 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 1e34e0b..395b557 100644
--- a/README.md
+++ b/README.md
@@ -7,12 +7,38 @@
   </a>
 </p>
 
-rmoa-action analyzes an OpenAPI definition file using the Rate My OpenAPI API,
-and reports the issues as console output, annotations and action summary.
+At Zuplo we believe that the better the quality of an OpenAPI document, the
+better the developer experience will be for the consumers of that API. This
+experience is important for the success of an API.
 
-The goal of rmoa-action is to help you establish best practices for your
-OpenAPI's definitions across multiple categories that include security,
-documentation and more.
+Rate My OpenAPI is a suite of tools designed to help software developers using
+OpenAPI to meet high standards of quality and usability when designing and
+developing their APIs.
+
+rmoa-action is part of this suite of tools. It analyzes an OpenAPI definition
+file using the Rate My OpenAPI API, and reports the issues as console output,
+annotations and action summary.
+
+The goal of rmoa-action is to help you establish best practices & continuous
+quality monitoring for your OpenAPI's definitions by seamlessly integrating it
+to your repository & development workflow.
+
+### Categories of Evaluation
+
+Our tools evaluate your OpenAPI definition files and provide a comprehensive
+score based on four key categories:
+
+- <b>Documentation:</b> Ensure your API is well-documented, making it easy for
+  users to understand and use.
+- <b>SDK Generation:</b> Verify that your API definition supports SDK
+  generation, facilitating integration and usage in different programming
+  languages.
+- <b>Security:</b> Check for best practices and standards to ensure your API is
+  secure and protected against common vulnerabilities.
+- <b>Completeness:</b> Ensure your API definition is complete, with all
+  necessary endpoints, parameters, and responses accurately defined.
+
+### Features
 
 This action provides the following functionality for GitHub Actions users:
 
@@ -23,12 +49,47 @@ This action provides the following functionality for GitHub Actions users:
 
 ## Usage
 
-Lint & get a score for your OpenAPI definition. You'll need to create a free api
-key at the [Rate My Open API Portal](https://api.ratemyopenapi.com/docs).
+To get started add our GitHub action to your repository & configure it to run on
+Pull Requests and Pushes to ensure continuous quality monitoring.
 
-See [action.yml](action.yml)
+### Getting an API Key
+
+You will need an API key as the GitHub Action uses the Rate My OpenAPI APIs
+which require the use of an API Key. You can sign up for free at
+(https://api.ratemyopenapi.com/docs)[https://api.ratemyopenapi.com/docs] to get
+your API Key.
+
+### Basic Setup
 
-<!-- start usage -->
+Lint an OpenAPI definition file using the default configuration
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: zuplo/rmoa-action@v1
+    with:
+      filepath: './my-api.json'
+      apikey: ${{ secrets.RMOA_API_KEY }}
+```
+
+### Advanced Setup
+
+Lint an OpenAPI definition and override the minimum passing score (default is 80
+out of 100) and set the maximum number of allowed warnings & errors.
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: zuplo/rmoa-action@v1
+    with:
+      filepath: './my-api.json'
+      apikey: ${{ secrets.RMOA_API_KEY }}
+      max-errors: 0
+      max-warnings: 5
+      minimum-score: 70
+```
+
+**Configuration Options**
 
 ```yaml
 - uses: zuplo/rmoa-action@v1
@@ -49,18 +110,7 @@ See [action.yml](action.yml)
     minimum-score: ''
 ```
 
-<!-- end usage -->
-
-**Basic:**
-
-```yaml
-steps:
-  - uses: actions/checkout@v4
-  - uses: zuplo/rmoa-action@v1
-    with:
-      filepath: './my-api.json'
-      apikey: ${{ secrets.RMOA_API_KEY }}
-```
+See [action.yml](action.yml)
 
 ## License