adds standard example for oas-3.1

examples/1-standard-oas-3.1/README.md

@@ -0,0 +1,28 @@
+# example
+
+simple example using express-openapi-validator
+
+## Install
+
+```shell
+npm run deps && npm i
+```
+
+## Run
+
+From this `1-standard` directory, run:
+
+```shell
+npm start
+```
+
+## Try
+
+```shell
+## call ping
+curl http://localhost:3000/v1/ping
+
+## call pets
+## the call below should return 400 since it requires additional parameters
+curl http://localhost:3000/v1/pets
+```

examples/1-standard-oas-3.1/api.yaml

@@ -0,0 +1,121 @@
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+servers:
+  - url: http://petstore.swagger.io/v1
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      parameters:
+        - name: limit
+          in: query
+          description: How many items to return at one time (max 100)
+          required: false
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '200':
+          description: A paged array of pets
+          headers:
+            x-next:
+              description: A link to the next page of responses
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pets'
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    post:
+      summary: Create a pet
+      operationId: createPets
+      tags:
+        - pets
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+      responses:
+        '201':
+          description: Null response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /pets/{petId}:
+    get:
+      summary: Info for a specific pet
+      operationId: showPetById
+      tags:
+        - pets
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          description: The id of the pet to retrieve
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Pets:
+      type: array
+      items:
+        $ref: '#/components/schemas/Pet'
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string

examples/1-standard-oas-3.1/app.js

@@ -0,0 +1,91 @@
+const express = require('express');
+const path = require('path');
+const http = require('http');
+const cookieParser = require('cookie-parser'); // Add if using cookie auth
+const { Pets } = require('./services');
+const OpenApiValidator = require('express-openapi-validator');
+
+const port = 3000;
+const app = express();
+const apiSpec = path.join(__dirname, 'api.yaml');
+
+// 1. Install bodyParsers for the request types your API will support
+app.use(express.urlencoded({ extended: false }));
+app.use(express.text());
+app.use(express.json());
+app.use(cookieParser()); // Add if using cookie auth enables req.cookies
+
+// Optionally serve the API spec
+app.use('/spec', express.static(apiSpec));
+
+//  2. Install the OpenApiValidator on your express app
+app.use(
+  OpenApiValidator.middleware({
+    apiSpec,
+    validateRequests: {
+      coerceTypes: true
+    },
+    validateResponses: true, // default false
+  }),
+);
+
+const pets = new Pets();
+// 3. Add routes
+app.get('/v1/ping', function (req, res, next) {
+  res.send('pong');
+});
+app.get('/v1/pets', function (req, res, next) {
+  res.json(pets.findAll(req.query));
+});
+
+app.post('/v1/pets', function (req, res, next) {
+  res.status(201).json(pets.create(req.body));
+});
+
+app.delete('/v1/pets/:id', function (req, res, next) {
+  res.json(pets.delete(req.params.id));
+});
+
+app.get('/v1/pets/:id', function (req, res, next) {
+  console.log(req.params.id)
+  const pet = pets.findById(req.params.id);
+  console.log(pet);  
+  return pet
+    ? res.json({ ...pet })
+    : res.status(404).json({ message: 'not found', code: 23 });
+});
+
+// 3a. Add a route upload file(s)
+app.post('/v1/pets/:id/photos', function (req, res, next) {
+  // DO something with the file
+  // files are found in req.files
+  // non file multipar params are in req.body['my-param']
+  console.log(req.files);
+
+  res.json({
+    files_metadata: req.files.map((f) => ({
+      originalname: f.originalname,
+      encoding: f.encoding,
+      mimetype: f.mimetype,
+      // Buffer of file conents
+      // buffer: f.buffer,
+    })),
+  });
+});
+
+// 4. Create a custom error handler
+app.use((err, req, res, next) => {
+  // format errors
+  // console.log(err)
+  res.status(err.status || 500).json({
+    message: err.message,
+    errors: err.errors,
+    code: err.status ?? 500,
+  });
+});
+
+
+http.createServer(app).listen(port);
+console.log(`Listening on port ${port}`);
+
+module.exports = app;