Merge pull request #5 from sergeyklay/feature/examples

Reformat OpenAPI spec
sergeyklay · Feb 6, 2023 · 30608a1 · 30608a1
2 parents 5a9cb46 + 68e6ece
commit 30608a1
Show file tree

Hide file tree

Showing 11 changed files with 7,079 additions and 72 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -18,3 +18,11 @@ updates:
       interval: daily
     assignees:
       - sergeyklay
+
+  - package-ecosystem: npm
+    # package.json stored in repository root.
+    directory: /
+    schedule:
+      interval: daily
+    assignees:
+      - sergeyklay
diff --git a/.github/workflows/contracts.yaml b/.github/workflows/contracts.yaml
@@ -3,7 +3,7 @@ name: Check Contracts
 on: [push]
 
 jobs:
-  hello_world_job:
+  check-contracts:
 
     runs-on: ${{ matrix.os }}
     name: Test Contracts
@@ -20,8 +20,10 @@ jobs:
           - windows-latest
 
     steps:
-      - name: Checkout
+      - name: Check out code
         uses: actions/checkout@v3
+        with:
+          fetch-depth: '0'
 
       - name: Set up Python 3.11
         uses: actions/setup-python@v4

diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
@@ -0,0 +1,33 @@
+name: Lint OpenAPI
+
+on:
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+  push:
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  lint-openapi:
+    name: Lint OpenAPI spec
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: '0'
+
+      - name: Setup Node.js 16.x
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Install linters
+        run: npm run lint
diff --git a/.github/workflows/versions.yaml b/.github/workflows/versions.yaml
@@ -3,7 +3,7 @@ name: Validate Action
 on: [push]
 
 jobs:
-  hello_world_job:
+  validate-action:
 
     runs-on: ${{ matrix.os }}
     name: Test Specmatic Installation
@@ -20,8 +20,10 @@ jobs:
           - windows-latest
 
     steps:
-      - name: Checkout
+      - name: Check out code
         uses: actions/checkout@v3
+        with:
+          fetch-depth: '0'
 
       - name: Check cache before install
         if: matrix.os != 'windows-latest'

diff --git a/.gitignore b/.gitignore
@@ -1 +1,7 @@
+# Directories to ignore (do not add trailing '/'s, they skip symlinks):
+# Dependency directory
+/node_modules
+
+# Python cache.
+*.py[cod]
 __pycache__
diff --git a/README.md b/README.md
@@ -2,6 +2,7 @@
 
 [![Check Contracts](https://github.com/sergeyklay/specmatic-testing-example/actions/workflows/contracts.yaml/badge.svg)](https://github.com/sergeyklay/specmatic-testing-example/actions/workflows/contracts.yaml)
 [![Validate Action](https://github.com/sergeyklay/specmatic-testing-example/actions/workflows/versions.yaml/badge.svg)](https://github.com/sergeyklay/specmatic-testing-example/actions/workflows/versions.yaml)
+[![Lint OpenAPI](https://github.com/sergeyklay/specmatic-testing-example/actions/workflows/lint.yaml/badge.svg)](https://github.com/sergeyklay/specmatic-testing-example/actions/workflows/lint.yaml)
 
 ## How to try it out
 

diff --git a/contracts/documentation.yaml b/contracts/documentation.yaml
@@ -3,8 +3,11 @@ openapi: 3.0.3
 
 info:
   version: '1.0'
-  title: Products API
+  title: Products API Definition
   description: Example API to test Specmatic features.
+  license:
+    name: MIT License
+    url: https://opensource.org/licenses/MIT
 
 servers:
   - description: Localhost
@@ -15,46 +18,16 @@ tags:
     description: Products related API.
 
 components:
-  parameters:
-    AcceptHeader:
-      in: header
-      name: Accept
-      description: Accept Header
-      schema:
-        type: string
-        enum: [application/json, '*/*']
-      example: application/json
-    IdParam:
-      in: path
-      name: id
-      description: Entity ID param
-      schema:
-        type: integer
-        format: int32
-        minimum: 1
-      required: true
-      example: 42
-
   schemas:
     Product:
       title: Product
-      allOf:
-        - $ref: '#/components/schemas/ProductId'
-        - $ref: '#/components/schemas/ProductDetails'
-    ProductId:
-      title: Product ID
       type: object
       properties:
         id:
           type: integer
           format: int32
           minimum: 1
           example: 42
-      required: [id]
-    ProductDetails:
-      title: Product Details
-      type: object
-      properties:
         title:
           type: string
           example: iPhone 9
@@ -85,6 +58,7 @@ components:
         category:
           $ref: '#/components/schemas/ProductCategory'
       required:
+        - id
         - title
         - description
         - price
@@ -104,25 +78,31 @@ components:
 paths:
   /v1/products:
     get:
-      summary: List of all products.
+      summary: Get products
+      description: Returns a list of all products.
       operationId: products.index
       tags: [products]
       parameters:
-        - $ref: '#/components/parameters/AcceptHeader'
-        - name: category
+        - in: query
+          name: category
           description: Filter by product category.
-          in: query
           required: false
           schema:
             type: string
-          example: laptops
-        - name: q
+          examples:
+            single:
+              value: laptops
+              summary: A sample category to filter products.
+        - in: query
+          name: q
           description: Search term.
-          in: query
           required: false
           schema:
             type: string
-          example: samsung
+          examples:
+            term:
+              value: Samsung
+              summary: A sample search keyword.
       responses:
         '200':
           description: List of products
@@ -132,15 +112,45 @@ paths:
                 type: array
                 items:
                   $ref: '#/components/schemas/Product'
+              examples:
+                products:
+                  value:
+                    - id: 1
+                      title: iPhone 9
+                      description: An apple mobile which is nothing like apple
+                      price: 549
+                      discount: 12.96
+                      rating: 4.69
+                      stock: 94
+                      brand: Apple
+                      category: smartphones
+                    - id: 6
+                      title: Samsung Galaxy Book
+                      description: Samsung Galaxy Book S (2020) Laptop With Intel Lakefield Chip, 8GB of RAM Launched
+                      price: 1499
+                      discount: 4.15
+                      rating: 4.25
+                      stock: 50
+                      brand: Samsung
+                      category: laptops
+                  summary: A sample list of products.
 
   '/v1/products/{id}':
     get:
-      summary: Get product.
+      summary: Get single product
+      description: Returns a single product.
       operationId: products.get
       tags: [products]
       parameters:
-        - $ref: '#/components/parameters/AcceptHeader'
-        - $ref: '#/components/parameters/IdParam'
+        - in: path
+          name: id
+          description: Entity ID param
+          schema:
+            type: integer
+            format: int32
+            minimum: 1
+          required: true
+          example: 42
       responses:
         '200':
           description: Get product

diff --git a/contracts/products.spec b/contracts/products.spec
@@ -5,55 +5,43 @@ Feature: Products API
 
   Scenario Outline: Bad request when getting the product by ID
     When GET /v1/products/(id:number)
-    And request-header Accept? (string)
     Then status 400
     Examples:
-      | id  | Accept           |
-      | 1.1 | application/json |
+      | id  |
+      | 1.1 |
 
   Scenario Outline: Product not found
     When GET /v1/products/(id:number)
-    And request-header Accept? (string)
     Then status 404
     Examples:
-      | id  | Accept           |
-      | 100 | application/json |
+      | id  |
+      | 100 |
 
   Scenario Outline: Successful getting product by ID
     When GET /v1/products/(id:number)
-    And request-header Accept? (string)
     Then status 200
     Examples:
-      | id | Accept           |
-      | 1  | application/json |
+      | id |
+      | 1  |
 
   Scenario Outline: Successful getting list of products
     When GET /v1/products
-    And request-header Accept? (string)
     Then status 200
-    Examples:
-      | Accept           |
-      | application/json |
-      | */*              |
 
   Scenario Outline: Successful getting list of products in a given category
     When GET /v1/products?category=(category:string)
-    And request-header Accept? (string)
     Then status 200
     Examples:
-      | Accept           | category    |
-      | application/json | smartphones |
-      | application/json | laptops     |
-      | */*              | smartphones |
-      | */*              |             |
+      | category    |
+      | smartphones |
+      | laptops     |
+      |             |
 
   Scenario Outline: Successful getting list of products using search term
     When GET /v1/products?q=(q:string)
-    And request-header Accept? (string)
     Then status 200
     Examples:
-      | Accept           | q     |
-      | application/json | phone |
-      | application/json |       |
-      | */*              | HP    |
-      | */*              |       |
+      | q     |
+      | phone |
+      | HP    |
+      |       |