Merge pull request #8 from grid-x/feat/improve-docs

feat: Improve documentation

Author: wwerner

.github/workflows/ci.yml

@@ -31,5 +31,5 @@ jobs:
       - name: Verify Output
         run: |
           stat ./petstore-with-samples.json
-          cat ./petstore-with-samples.json | grep 'x-code-samples'
+          grep 'x-code-samples' < petstore-with-samples.json
         shell: bash

.github/workflows/linter.yml

@@ -47,3 +47,7 @@ jobs:
           VALIDATE_JAVASCRIPT_STANDARD: false
           VALIDATE_JSCPD: false
           VALIDATE_TYPESCRIPT_STANDARD: false
+          VALIDATE_OPENAPI: false
+          VALIDATE_CHECKOV: false
+          VALIDATE_MARKDOWN: false
+          VALIDATE_MARKDOWN_PRETTIER: false

README.md

@@ -1,6 +1,44 @@
 # Generate Code Snippets from an OpenAPI specification
 
-TODO: Synopsis
+This GitHub Action takes an OpenAPI spec, generates code samples for each
+operation and adds them to the spec using
+[the `x-code-samples` extension](https://redocly.com/docs/api-reference-docs/specification-extensions/x-code-samples).
+
+If you
+[specified `examples` in your endpoint](https://swagger.io/docs/specification/adding-examples/),
+it takes the first example as the payload when generating snippets. If there is
+no example, the payload will be empty/`null`.
+
+The following languages are supported:
+
+- `c`
+- `clojure`
+- `csharp`
+- `go`
+- `http`
+- `java`
+- `javascript`
+- `json`
+- `kotlin`
+- `node`
+- `cplusplus`
+- `objectivec`
+- `ocaml`
+- `php`
+- `powershell`
+- `python`
+- `r`
+- `ruby`
+- `shell`
+- `swift`
+
+The results look like this.
+
+![readme.com](./docs/readme.png) _readme.com_
+
+![rapidoc](./docs/rapidoc.png) _RapiDoc_
+
+![redoc](./docs/redoc.png) _Redoc_
 
 ## Prerequisites / Inputs
 
@@ -11,7 +49,18 @@ TODO: Synopsis
 
 ## Instructions
 
-1. ...
+Add a GitHub Action in your workflow, passing the input spec file (json or
+YAML), the desired output file location (json) and, optionally, the list of
+languages to generate snippets for.
+
+```yaml
+- name: Generate Code Samples
+  uses: grid-x/api-spec-snippets-generator-action@v6
+  with:
+    spec_file: ./petstore.yaml
+    out_file: ./petstore-with-samples.json
+    languages: go,python,shell,java,kotlin,swift,csharp
+```
 
 ## Development
 

badges/coverage.svg

@@ -77,6 +77,10 @@ const label = (lang: SupportedTargets): string => {
   switch (lang) {
     case 'csharp':
       return 'C#'
+    case 'cplusplus':
+      return 'C++'
+    case 'objectivec':
+      return 'Objective-C'
     default:
       return lang.charAt(0).toUpperCase() + lang.slice(1)
   }