Updated READMEs

knom · Apr 20, 2021 · 5a60447 · 5a60447
1 parent e6c454a
commit 5a60447
Show file tree

Hide file tree

Showing 13 changed files with 225 additions and 144 deletions.
diff --git a/1.png b/1.png
diff --git a/README.md b/README.md
@@ -1,4 +1,5 @@
-# OpenAPI Contract Diff [![Version](https://img.shields.io/vscode-marketplace/v/knom.vsts-swagger-diff.svg?label=VS%20Marketplace&logo=visual-studio-code&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=knom.vsts-swagger-diff) [![Visual Studio Marketplace Downloads](https://img.shields.io/vscode-marketplace/d/knom.vsts-swagger-diff.svg?logo=visual-studio-code&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=knom.vsts-swagger-diff) [![GitHub License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/knom/vsts-swagger-tasks/blob/master/LICENSE) ![Build Status](https://knom-msft.visualstudio.com/_apis/public/build/definitions/9d8fcb7c-6c11-4014-9dc2-7966c94af2b2/7/badge)
+# OpenAPI Contract Diff 
+[![Version](https://img.shields.io/vscode-marketplace/v/knom.vsts-swagger-diff.svg?label=VS%20Marketplace&logo=visual-studio-code&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=knom.vsts-swagger-diff) [![Visual Studio Marketplace Downloads](https://img.shields.io/vscode-marketplace/d/knom.vsts-swagger-diff.svg?logo=visual-studio-code&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=knom.vsts-swagger-diff) [![GitHub License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/knom/vsts-swagger-tasks/blob/master/LICENSE) ![Build Status](https://knom-msft.visualstudio.com/_apis/public/build/definitions/9d8fcb7c-6c11-4014-9dc2-7966c94af2b2/7/badge)
 
 A build/release task for comparing OpenAPI Contracts.
 
@@ -13,7 +14,26 @@ You can use the task for making sure a certain Swagger contract still is in comp
 **If an ERROR occurs, the task will per default STOP the build or release pipeline. Hence it can act as a quality gate for e.g. a release**
 
 > Note: The task is using the following libraries...
-* https://www.npmjs.com/package/swagger-diff for 2.0
-* https://www.npmjs.com/package/openapi-diff for 3.0
+> * https://www.npmjs.com/package/swagger-diff for 2.0
+> * https://www.npmjs.com/package/openapi-diff for 3.0
 
-```
+
+## Usage
+Configure the schema version of the contract (both have to have the same version)
+* OpenAPI (3.0)
+* Swagger (2.0)
+
+Add left- and right-side contract, which can be
+* a file on the build agent
+* a publicly accessible URL
+
+![Usage](src/docs/task.png)
+
+## Output
+### Sample output of diff-comparison of two **OpenAPI v3 contracts**
+![Result1](src/docs/result1.png)
+
+> Note: Right now OpenAPI DIFF is way less detailed than Swagger one is. This is back to the output of the underlying libraries.
+
+### Sample output of diff-comparison of two **Swagger v2 contracts**
+![Result2](src/docs/result2.png)
diff --git a/gulpfile.js b/gulpfile.js
@@ -121,9 +121,7 @@ gulp.task(
       .src(
         [
           "./extension-icon*.png",
-          "LICENSE.md",
           "PRIVACY.md",
-          "README.md",
           "package.json",
           "docs/**/*",
           "!src/**",

diff --git a/icon.svg b/icon.svg
diff --git a/src/README.md b/src/README.md
diff --git a/LICENSE.md → src/docs/LICENSE.md b/LICENSE.md → src/docs/LICENSE.md
@@ -1,4 +1,4 @@
-# VSTS Swagger Diff Build/RM Tasks
+# OpenAPI Contract Diff
 
 Copyright (c) 2021 knom
 

diff --git a/src/docs/OVERVIEW.md b/src/docs/OVERVIEW.md
@@ -0,0 +1,39 @@
+# OpenAPI Contract Diff 
+[![Version](https://img.shields.io/vscode-marketplace/v/knom.vsts-swagger-diff.svg?label=VS%20Marketplace&logo=visual-studio-code&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=knom.vsts-swagger-diff) [![Visual Studio Marketplace Downloads](https://img.shields.io/vscode-marketplace/d/knom.vsts-swagger-diff.svg?logo=visual-studio-code&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=knom.vsts-swagger-diff) [![GitHub License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/knom/vsts-swagger-tasks/blob/master/LICENSE) ![Build Status](https://knom-msft.visualstudio.com/_apis/public/build/definitions/9d8fcb7c-6c11-4014-9dc2-7966c94af2b2/7/badge)
+
+A build/release task for comparing OpenAPI Contracts.
+
+Pass in URLs or Paths of OpenAPI (3.0) or Swagger (2.0) Contracts.
+
+The task will compare the two contracts "left-side" and "right-side".
+
+It will output any **differences** as **info, warning, errors** depending on the configuration.
+
+You can use the task for making sure a certain Swagger contract still is in compliance with a specification.
+
+**If an ERROR occurs, the task will per default STOP the build or release pipeline. Hence it can act as a quality gate for e.g. a release**
+
+> Note: The task is using the following libraries...
+> * https://www.npmjs.com/package/swagger-diff for 2.0
+> * https://www.npmjs.com/package/openapi-diff for 3.0
+
+
+## Usage
+Configure the schema version of the contract (both have to have the same version)
+* OpenAPI (3.0)
+* Swagger (2.0)
+
+Add left- and right-side contract, which can be
+* a file on the build agent
+* a publicly accessible URL
+
+![Usage](docs/task.png)
+
+## Output
+### Sample output of diff-comparison of two **OpenAPI v3 contracts**
+![Result1](docs/result1.png)
+
+> Note: Right now OpenAPI DIFF is way less detailed than Swagger one is. This is back to the output of the underlying libraries.
+
+### Sample output of diff-comparison of two **Swagger v2 contracts**
+![Result2](docs/result2.png)
diff --git a/src/docs/result1.png b/src/docs/result1.png
diff --git a/src/docs/result2.png b/src/docs/result2.png
diff --git a/src/docs/task.png b/src/docs/task.png
diff --git a/src/images/logo.png b/src/images/logo.png
diff --git a/src/images/logo_large.png b/src/images/logo_large.png
diff --git a/src/vss-extension.json b/src/vss-extension.json
@@ -52,7 +52,8 @@
     "color": "#777",
     "theme": "dark"
   },
-  "screenshots": [{
+  "screenshots": [
+    {
       "path": "docs/task.png"
     },
     {
@@ -64,28 +65,40 @@
   ],
   "content": {
     "details": {
-      "path": "README.md"
+      "path": "docs/OVERVIEW.md"
+    },
+    "license": {
+      "path": "docs/LICENSE.md"
     }
   },
-  "files": [{
+  "files": [
+    {
       "path": "images",
       "addressable": true
     },
+    {
+      "path": "docs",
+      "addressable": true
+    },
     {
       "path": "swagger-diff"
     }
   ],
-  "targets": [{
-    "id": "Microsoft.VisualStudio.Services"
-  }],
-  "contributions": [{
-    "id": "swagger-diff",
-    "type": "ms.vss-distributed-task.task",
-    "targets": [
-      "ms.vss-distributed-task.tasks"
-    ],
-    "properties": {
-      "name": "swagger-diff"
+  "targets": [
+    {
+      "id": "Microsoft.VisualStudio.Services"
+    }
+  ],
+  "contributions": [
+    {
+      "id": "swagger-diff",
+      "type": "ms.vss-distributed-task.task",
+      "targets": [
+        "ms.vss-distributed-task.tasks"
+      ],
+      "properties": {
+        "name": "swagger-diff"
+      }
     }
-  }]
+  ]
 }