Merge pull request #5 from temando/readme

Readme

Author: nfour

README.md

@@ -1,38 +1,28 @@
-# Serverless OpenAPI v3 Documentation Plugin
 
-This plugin generates OpenAPI v3 documentation from serverless configuration files. OpenAPI is formerly known as Swagger. The configuration is extends the format specified by [serverless-aws-documentation](https://www.npmjs.com/package/serverless-aws-documentation).
+[![Travis CI](https://img.shields.io/travis/temando/serverless-openapi-documentation.svg)](https://travis-ci.org/temando/serverless-openapi-documentation)
+[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 
 
-## Install
-
-This plugin works for Serverless 1.x and up. Serverless 0.5 is not supported.
-
-To add this plugin to your package.json:
-
-**Using npm:**
-```bash
-npm install serverless-openapi-documentation --save-dev
-```
-
-**Using Yarn:**
-```bash
-yarn add serverless-openapi-documentation --dev
-```
-
-Next you need to add the plugin to the `plugins` section of your `serverless.yml` file.
+# Serverless OpenAPI Documentation Plugin
 
-```yml
-plugins:
-  - serverless-openapi-documentation
-```
+Generates [**OpenAPI 3.0 RC2**](https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.next) documentation from serverless configuration files. OpenAPI is formerly known as Swagger. The configuration is inspired by the format used in [serverless-aws-documentation](https://www.npmjs.com/package/serverless-aws-documentation).
 
-You can confirm the plugin is correctly installed by running:
+---
 
-```bash
-serverless | grep "ServerlessOpenAPIDocumentation"
-```
+- [Usage](#usage)
+  - [Options](#options)
+  - [Configuration](#configuration)
+    - [Models](#models)
+    - [Functions](#functions)
+    - [`queryParams`](#queryparams)
+    - [`pathParams`](#pathparams)
+    - [`cookieParams`](#cookieparams)
+    - [`requestModels`](#requestmodels)
+    - [`methodResponses`](#methodresponses)
+- [Example Configuration](#example-configuration)
+- [Install](#install)
 
-It should return `ServerlessOpenAPIDocumentation` as one of the plugins on the list.
+---
 
 ## Usage
 
@@ -43,7 +33,9 @@ Below are the commandline options to run the generator:
 ```bash
 serverless openapi generate [options]
 ```
+
 ### Options
+
 ```bash
 Plugin: ServerlessOpenAPIDocumentation
 openapi generate  ...................... Generate OpenAPI v3 Documentation
@@ -57,7 +49,7 @@ openapi generate  ...................... Generate OpenAPI v3 Documentation
 
 To configure this plugin to generate valid OpenAPI documentation there are two places you'll need to modify in your `serverless.yml` file, the `custom` variables section and the `http` event section for each given function in your service.
 
-This plugin is compatible with the same documentation configuration as per [serverless-aws-documentation](https://www.npmjs.com/package/serverless-aws-documentation) and can run beside it.
+This plugin is compatible with the same documentation configuration structure in [serverless-aws-documentation](https://www.npmjs.com/package/serverless-aws-documentation) and can run beside it.
 
 The `custom` section of your `serverless.yml` can be configured as below:
 
@@ -67,18 +59,27 @@ custom:
     version: '1'
     summary: 'My API'
     description: 'This is my API'
+    models: {}
 ```
 
-If you find this configuration too verbose, you can separate it out into it's own file, such as `serverless.doc.yml` by replacing it with the following:
+These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
 
 ```yml
 custom:
   documentation: ${file(serverless.doc.yml):documentation}
+
+functions:
+  myFunc:
+    events:
+      - http:
+          path: getStuff
+          method: get
+          documentation: ${file(serverless.doc.yml):endpoints.myFunc}
 ```
 
-And instead putting the `documentation` section directly into `serverless.doc.yml`.
+For more info on `serverless.yml` syntax, see their docs.
 
-#### Defining models
+#### Models
 
 Models contain additional information that you can use to define schemas for endpoints.  You must define the *content type* for each schema that you provide in the models.
 
@@ -114,7 +115,7 @@ custom:
                   type: "string"
 ```
 
-### Function event specific documentation
+#### Functions
 
 To define the documentation for a given function event, you need to create a `documentation` attribute for your http event in your `serverless.yml` file.
 
@@ -182,7 +183,7 @@ functions:
                 application/json: "ErrorResponse"
 ```
 
-#### queryParams
+#### `queryParams`
 
 Query parameters can be described as follow:
 
@@ -200,7 +201,7 @@ queryParams:
       type: "string"
 ```
 
-#### pathParams
+#### `pathParams`
 
 Path parameters can be described as follow:
 
@@ -216,7 +217,7 @@ pathParams:
       type: "string"
 ```
 
-#### cookieParams
+#### `cookieParams`
 
 Cookie parameters can be described as follow:
 
@@ -234,7 +235,7 @@ cookieParams:
       type: "string"
 ```
 
-#### requestModels
+#### `requestModels`
 
 The `requestModels` property allows you to define models for the HTTP Request of the function event. You can define a different model for each different `Content-Type`. You can define a reference to the relevant request model named in the `models` section of your configuration (see [Defining Models](#defining-models) section).
 
@@ -244,7 +245,7 @@ requestModels:
   application/xml: "CreateRequestXML"
 ```
 
-#### methodResponses
+#### `methodResponses`
 
 You can define the response schemas by defining properties for your function event.
 
@@ -263,7 +264,7 @@ methodResponse:
       application/xml: "CreateResponseXML"
 ```
 
-##### responseModels
+##### `responseModels`
 
 The `responseModels` property allows you to define models for the HTTP Response of the function event. You can define a different model for each different `Content-Type`. You can define a reference to the relevant response model named in the `models` section of your configuration (see [Defining Models](#defining-models) section).
 
@@ -273,7 +274,7 @@ responseModels:
   application/xml: "CreateResponseXML"
 ```
 
-##### responseHeaders
+##### `responseHeaders`
 
 The `responseHeaders` section of the configuration allows you to define the HTTP response headers for the function event.
 
@@ -295,8 +296,37 @@ responseHeaders:
 
 Please view the example [serverless.yml](test/serverless.yml).
 
-## Contribution
-`Insert: information on contibution here`
+## Install
+
+This plugin works for Serverless 1.x and up. Serverless 0.5 is not supported.
+
+To add this plugin to your package.json:
+
+**Using npm:**
+```bash
+npm install serverless-openapi-documentation --save-dev
+```
+
+**Using Yarn:**
+```bash
+yarn add serverless-openapi-documentation --dev
+```
+
+Next you need to add the plugin to the `plugins` section of your `serverless.yml` file.
+
+```yml
+plugins:
+  - serverless-openapi-documentation
+```
+
+You can confirm the plugin is correctly installed by running:
+
+```bash
+serverless | grep "ServerlessOpenAPIDocumentation"
+```
+
+It should return `ServerlessOpenAPIDocumentation` as one of the plugins on the list.
+
 
 ## License
 

src/DefinitionGenerator.ts

@@ -195,6 +195,10 @@ export class DefinitionGenerator {
   private getRequestBodiesFromConfig (documentationConfig) {
     const requestBodies = {};
 
+    if (!documentationConfig.requestModels) {
+      throw new Error(`Required requestModels in: ${JSON.stringify(documentationConfig, null, 2)}`);
+    }
+
     // Does this event have a request model?
     if (documentationConfig.requestModels) {
       // For each request model type (Sorted by "Content-Type")
@@ -211,7 +215,7 @@ export class DefinitionGenerator {
             },
           };
 
-          this.applyExamples(requestModel, reqModelConfig);
+          this.attachExamples(requestModel, reqModelConfig);
 
           const reqBodyConfig: { content: object, description?: string } = {
             content: {
@@ -231,7 +235,7 @@ export class DefinitionGenerator {
     return requestBodies;
   }
 
-  private applyExamples (target, config) {
+  private attachExamples (target, config) {
     if (target.examples && Array.isArray(target.examples)) {
       merge(config, { examples: clone(target.examples) });
     } else if (target.example) {
@@ -292,7 +296,7 @@ export class DefinitionGenerator {
           },
         };
 
-        this.applyExamples(responseModel, resModelConfig);
+        this.attachExamples(responseModel, resModelConfig);
 
         merge(content, { [responseKey] : resModelConfig });
       }

src/ServerlessOpenApiDocumentation.ts

@@ -132,6 +132,7 @@ export class ServerlessOpenApiDocumentation {
 
       for (const info of validation.error) {
         this.log(c.grey('\n\n--------\n\n'));
+        this.log(' ', c.blue(info.dataPath), '\n');
         this.log(' ', info.schemaPath, c.bold.yellow(info.message));
         this.log(c.grey('\n\n--------\n\n'));
         this.log(`${inspect(info, { colors: true, depth: 2 })}\n\n`);