Updates

- Add missing `requestBody` and `responseBody` directives
- Clean schemas for params and request/response headers
- Add missing response headers
- WIP: README.md
- Add demo serverless.yml

Author: Abilio Henrique

README.md

@@ -0,0 +1,303 @@
+# 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).
+
+
+## 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.
+
+## Usage
+
+This plugin requires additional configuration to use, see the "[Configuration](#configuration)" section for how to configure the plugin to generate documentation.
+
+Below are the commandline options to run the generator:
+
+```bash
+serverless openapi generate [options]
+```
+### Options
+```bash
+Plugin: ServerlessOpenAPIDocumentation
+openapi generate  ...................... Generate OpenAPI v3 Documentation
+    --output / -o ...................... Output file location [default: openapi.yml|json]
+    --format / -f ...................... OpenAPI file format (yml|json) [default: yml]
+    --indent / -i ...................... File indentation in spaces[default: 2]
+    --help / -h   ...................... Help
+```
+
+### Configuration
+
+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.
+
+The `custom` section of your `serverless.yml` can be configured as below:
+
+```yml
+custom:
+  documentation:
+    version: '1'
+    summary: 'My API'
+    description: 'This is my API'
+```
+
+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:
+
+```yml
+custom:
+  documentation: ${file(serverless.doc.yml):documentation}
+```
+
+And instead putting the `documentation` section directly into `serverless.doc.yml`.
+
+#### Defining 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.
+
+The *required* directives for the models section are as follow:
+
+* `name`: the name of the schema
+* `description`: a description of the schema
+* `contentType`: the content type of the described request/response (ie. `application/json` or `application/xml`).
+* `schema`: The JSON Schema ([website](http://json-schema.org/)) that describes the model. You can either use inline `YAML` to define these, or refer to an external schema file as below
+
+```yml
+custom:
+  documentation:
+    models:
+      - name: "ErrorResponse"
+        description: "This is an error"
+        contentType: "application/json"
+        schema: ${file(models/ErrorResponse.json)}
+      - name: "PutDocumentResponse"
+        description: "PUT Document response model (external reference example)"
+        contentType: "application/json"
+        schema: ${file(models/PutDocumentResponse.json)}
+      - name: "PutDocumentRequest"
+        description: "PUT Document request model (inline example)"
+        contentType: "application/json"
+        schema:
+          $schema: "http://json-schema.org/draft-04/schema#"
+          properties:
+            SomeObject:
+              type: "object"
+              properties:
+                SomeAttribute:
+                  type: "string"
+```
+
+### Function event specific documentation
+
+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.
+
+The `documentation` section of the event configuration can contain the following attributes:
+
+* `summary`: a short description of the method
+* `description`: a detailed description of the method
+* `requestBody`: contains description of the request
+    * `description`: a description of the request body
+* `requestModels`: a list of models to describe the request bodies (see [requestModels](#requestModels) below)
+* `queryParams`: a list of query parameters (see [queryParams](#queryParams) below)
+* `pathParams`: a list of path parameters (see [pathParams](#pathParams) below)
+* `cookieParams`: a list of cookie parameters (see [cookieParams](#cookieParams) below)
+* `methodResponses`: an array of response models and applicable status codes
+  * `statusCode`: applicable http status code (ie. 200/404/500 etc.)
+  * `responseBody`: contains description of the response
+    * `description`: a description of the body response
+  * `responseHeaders`: a list of response headers (see [responseHeaders](#responseHeaders) below)
+  * `responseModels`: a list of models to describe the request bodies (see [responseModels](#responseModels) below) for each `Content-Type`
+
+```yml
+functions:
+  createUser:
+    handler: "handler.create"
+    events:
+      - http:
+        path: "create"
+        method: "post"
+        documentation:
+          summary: "Create User"
+          description: "Creates a user and then sends a generated password email"
+          requestBody:
+            description: "A user information object"
+          requestModels:
+            application/json: "PutDocumentRequest"
+          pathParams:
+            - name: "username"
+              description: "The username for a user to create"
+              schema:
+                type: "string"
+                pattern: "^[-a-z0-9_]+$"
+          queryParams:
+            - name: "membershipType"
+              description: "The user's Membership Type"
+              schema:
+                type: "string"
+                enum:
+                  - "premium"
+                  - "standard"
+          cookieParams:
+            - name: "SessionId"
+              description: "A Session ID variable"
+              schema: 
+                type: "string"
+          methodResponses:
+            - statusCode: 201
+              responseBody:
+                description: "A user object along with generated API Keys"
+              responseModels:
+                application/json: "PutDocumentResponse"
+            - statusCode: 500
+              responseBody:
+                description: "An error message when creating a new user"
+              responseModels:
+                application/json: "ErrorResponse"
+```
+
+#### queryParams
+
+Query parameters can be described as follow:
+
+* `name`: the name of the query variable
+* `description`: a description of the query variable
+* `required`: whether the query parameter is mandatory (boolean)
+* `schema`: JSON schema (inline or file)
+
+```yml
+queryParams:
+  - name: "filter"
+    description: "The filter parameter"
+    required: true
+    schema:
+      type: "string"
+```
+
+#### pathParams
+
+Path parameters can be described as follow:
+
+* `name`: the name of the query variable
+* `description`: a description of the query variable
+* `schema`: JSON schema (inline or file)
+
+```yml
+pathParams:
+  - name: "usernameId"
+    description: "The usernameId parameter"
+    schema:
+      type: "string"
+```
+
+#### cookieParams
+
+Cookie parameters can be described as follow:
+
+* `name`: the name of the query variable
+* `description`: a description of the query variable
+* `required`: whether the query parameter is mandatory (boolean)
+* `schema`: JSON schema (inline or file)
+
+```yml
+cookieParams:
+  - name: "sessionId"
+    description: "The sessionId parameter"
+    required: true
+    schema:
+      type: "string"
+```
+
+#### 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](#definingmodels) section).
+
+```yml
+requestModels:
+  application/json: "CreateRequest"
+  application/xml: "CreateRequestXML"
+```
+
+#### methodResponses
+
+You can define the response schemas by defining properties for your function event.
+
+For an example of a `methodResponses` configuration for an event see below:
+
+```yml
+methodResponse:
+  - statusCode: 200
+    responseHeaders:
+      - name: "Content-Type"
+        description: "Content Type header"
+        schema:
+          type: "string"
+    responseModels: 
+      application/json: "CreateResponse"
+      application/xml: "CreateResponseXML"
+```
+
+##### 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](#definingmodels) section).
+
+```yml
+responseModels:
+  application/json: "CreateResponse"
+  application/xml: "CreateResponseXML"
+```
+
+##### responseHeaders
+
+The `responseHeaders` section of the configuration allows you to define the HTTP response headers for the function event.
+
+The attributes for a response header are as follow:
+
+* `name`: the name of the HTTP Header
+* `description`: a description of the HTTP Header
+* `schema`: JSON schema (inline or file)
+
+```yml
+responseHeaders:
+  - name: "Content-Type"
+    description: "Content Type header"
+    schema:
+      type: "string"
+```
+
+## Example configuration
+
+Please view the example [serverless.yml](test/serverless.yml).
+
+## Contribution
+`Insert: information on contibution here`
+
+## License
+
+MIT

package.json

@@ -27,12 +27,12 @@
     "ts-node": "^3.0.2",
     "tslint": "^5.1.0",
     "tslint-eslint-rules": "^4.0.0",
+    "typedoc": "^0.5.10",
     "typescript": "^2.2.2"
   },
   "dependencies": {
     "@jdw/jst": "^1.0.0-beta.10",
     "@types/bluebird": "^3.5.2",
-    "@types/chalk": "^0.4.31",
     "@types/fs-promise": "^1.0.1",
     "@types/js-yaml": "^3.5.29",
     "bluebird": "^3.5.0",

src/generate.ts

@@ -97,7 +97,7 @@ export default class DocumentGenerator {
         }
       }
     }
-  };
+  }
 
   /**
    * Cleans schema objects to make them OpenAPI compatible
@@ -173,7 +173,7 @@ export default class DocumentGenerator {
 
         // console.log(parameter);
         if (parameter.schema) {
-          parameterConfig.schema = parameter.schema;
+          parameterConfig.schema = this.cleanSchema(parameter.schema);
         }
 
         if (parameter.example) {
@@ -220,9 +220,17 @@ export default class DocumentGenerator {
             merge(reqModelConfig, { example: clone(requestModel.example) });
           }
 
-          merge(requestBodies, {
-            [requestModelType]: reqModelConfig,
-          });
+          const reqBodyConfig: { content: object, description?: string } = {
+            content: {
+              [requestModelType]: reqModelConfig,
+            },
+          };
+
+          if (documentationConfig.requestBody && 'description' in documentationConfig.requestBody) {
+            reqBodyConfig.description = documentationConfig.requestBody.description;
+          }
+
+          merge(requestBodies, reqBodyConfig);
         }
       }
     }
@@ -238,11 +246,29 @@ export default class DocumentGenerator {
     const responses = {};
     if (documentationConfig.methodResponses) {
       for (const response of documentationConfig.methodResponses) {
+        const methodResponseConfig: { description: any, content: object, headers?: object } = {
+          description: (
+            (response.responseBody && 'description' in response.responseBody)
+              ? response.responseBody.description
+              : `Status ${response.statusCode} Response`
+          ),
+          content: this.getResponseContent(response.responseModels),
+        };
+
+        if (response.responseHeaders) {
+          methodResponseConfig.headers = {};
+          for (const header of response.responseHeaders) {
+            methodResponseConfig.headers[header.name] = {
+              description: header.description || `${header.name} header`,
+            };
+            if (header.schema) {
+              methodResponseConfig.headers[header.name].schema = this.cleanSchema(header.schema);
+            }
+          }
+        }
+
         merge(responses, {
-          [response.statusCode]: {
-            description: response.description || `Status ${response.statusCode} Response`,
-            content: this.getResponseContent(response.responseModels),
-          },
+          [response.statusCode]: methodResponseConfig,
          });
       }
     }