setup a scaffolded OpenAPI specification.

 - documents build process in README.md
 - endpoints in endpoints/*
 - JSON schemas in schemas/*
 - build tooling defined in package.json

Author: devjack

README.md

@@ -0,0 +1,31 @@
+# Example Library Specification
+This repository defines a simple API using [OpenAPI v3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md).
+
+# Setup and installation
+
+The API spec is defined in `openapi.yml`. Each URL has its own endpoint in `endpoints/` and JSON request/response schemas are defined in `schemas/`. JSON Schema is used to define responses and can be used for validation.
+
+## Setup and run the documentation
+Run these commands to install npm dependencies and serve the API documentation locally.
+
+```sh
+npm install
+npm run test
+npm run serve
+```
+
+The API documentation will be available at [https://localhost:5000](http://localhost:5000).
+
+To resolve and publish the API spec, run:
+
+```sh
+npm run resolve
+```
+
+A simple HTML document including [ReDoc](https://github.com/Rebilly/ReDoc) is available in the `public/` directory. To copy across the published spec and schemas, run:
+
+```sh
+npm run publish
+```
+
+You can then serve `/public` from any static content hosting service.

endpoints/ping.yml

@@ -0,0 +1,20 @@
+paths:
+    '/ping':
+        get:
+          operationId: ping
+          description: "Check to see that the application is ready to respond to requests."
+          tags:
+            - Ping
+          responses:
+            '200':
+              description: Successful ping; the application is ready to respond to requests
+              content:
+                application/json:
+                    schema:
+                        $ref: '../openapi.yml#/components/schemas/ping'
+            '500':
+              description: Unsuccessful ping; the application is NOT ready.
+              content:
+                application/json:
+                    schema:
+                        $ref: '../openapi.yml#/components/schemas/error'

openapi.yml

@@ -0,0 +1,84 @@
+openapi: 3.0.0
+info:
+    title: The Library
+    description: A simple library API
+    contact:
+      name: developerjack
+      url: https://www.twitter.com/developerjack
+    license:
+      name: Proprietary
+    version: 0.0.1 #Spec version/revision - not the API or product version
+
+servers:
+  - url: 'http://localhost:8080'
+    description: Local dev API.
+
+tags:
+  - name: User
+  #- name: Book
+  #- name: Loan
+
+paths:
+    /ping:
+       $ref: "endpoints/ping.yml#/paths/~1ping"
+    
+    # /user:
+    #    $ref: "endpoints/user.yml#/paths/~1user"
+    # todo: The user endpoints
+    # /user/{id}:
+    #    $ref: "endpoints/user.yml#/paths/~1user~1{id}"
+    
+    # todo: The book endpoints
+    # /book:
+    #    $ref: "endpoints/book.yml#/paths/~1book"
+    # /book/{id}:
+    #    $ref: "endpoints/book.yml#/paths/~1book~1{id}"
+    
+    # todo: The loan endpoints
+    # /loan:
+    #    $ref: "endpoints/loan.yml#/paths/~1loan"
+    # /loan/{id}:
+    #     $ref: "endpoints/loan.yml#/paths/~1loan~1{id}"
+
+components:
+    schemas:
+        ping:
+            $ref: 'schemas/ping.json'
+            
+        # todo: user resources
+        # user:
+        #     $ref: 'schemas/user.json'
+        # user-collection:
+        #     $ref: 'schemas/user-collection.json'
+        
+        # todo: book resources
+        # book:
+        #     $ref: 'schemas/book.json'
+        # book-collection:
+        #     $ref: 'schemas/book-collection.json'
+        
+        # todo: loan resources
+        # loan:
+        #     $ref: 'schemas/loan.json'
+        # loan-collection:
+        #     $ref: 'schemas/loan-collection.json'
+
+        error:
+            type: object
+            required:
+            - id
+            - message
+            properties:
+                id:
+                    type: string
+                    description: "Unique ID of this error. For example sake, use the HTTP status code."
+                    nullable: false
+                    example: "500"
+                message:
+                    type: string
+                    description: "A human readable message describing the nature of the error."
+                    nullable: false
+                path:
+                    type: string
+                    description: "A JSONpath reference to the field where the error occurred."
+                    nullable: true

package.json

@@ -0,0 +1,28 @@
+{
+  "name": "example-library-specification",
+  "version": "0.0.1",
+  "description": "An example library API definition",
+  "scripts": {
+    "test": "node_modules/.bin/speccy lint openapi.yml -j",
+    "resolve": "mkdir -p dist && node_modules/.bin/speccy resolve openapi.yml -j > dist/openapi.yml",
+    "serve": "node_modules/.bin/speccy serve openapi.yml -j",
+    "publish": "cp dist/openapi.yml public/openapi.yml && cp -R schemas public/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "[email protected]:devjack/example-library-specification.git"
+  },
+  "author": "Jack Skinner",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/devjack/example-library-specification/issues"
+  },
+  "homepage": "https://github.com/devjack/example-library-specification",
+  "devDependencies": {
+    "speccy": "^0.7"
+  },
+  "engines": {
+    "node": ">=10",
+    "npm": ">=5.6"
+  }
+}

schemas/ping.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "Ping/Pong resource for simple healthchecks.",
+    "required": [
+        "ping"
+    ],
+    "properties": {
+        "ping": {
+            "type": "string",
+            "description": "An acknowledgement tat the ping was received",
+            "default": "",
+            "example": "pong"
+        }
+    }
+}