Merge pull request #140 from JaredCE/best-practice-serverless

Best practice serverless

Author: JaredCE

README.md

@@ -751,6 +751,8 @@ requestModels:
 
 #### `methodResponses`
 
+`methodResponses` is a mandatory property and should include the `responseBody` and `description` properties.
+
 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:
@@ -763,6 +765,12 @@ methodResponse:
     responseModels:
       application/json: "CreateResponse"
       application/xml: "CreateResponseXML"
+    links:
+      getDataLink:
+        operation: getData
+        description: The id created here can be used to get Data
+        parameters:
+          contentId: $response.body#/id
     responseHeaders:
       X-Rate-Limit-Limit:
         description: The number of allowed requests in the current period
@@ -788,6 +796,53 @@ responseModels:
   application/xml: "CreateResponseXML"
 ```
 
+##### `links`
+
+The `links` property allows you to define how operations are linked to each other:
+
+```yml
+links:
+  linkName:
+    operation: getContent
+    description: The contentId created here can be used to get content
+    parameters:
+      contentId: $response.body#/contentId
+```
+
+Where we are specifying operation, this should map to the function name:
+
+```yml
+functions:
+  createContent:
+    events:
+      - httpApi:
+          path: /
+          method: POST
+          documentation: ...
+  getContent:
+    events:
+      - http:
+          path: /{contentId}
+          method: POST
+          documentation: ...
+```
+
+If our example link was attached to the **createContent** function, and we wanted the `contentId` that was created to be used on the **getContent** function in the `contentId` parameter, we'd specify the `operation` property as **getContent**. If however, you had specified an operationId in the documentation to override the automatically created one:
+
+```yml
+getContent:
+  events:
+    - http:
+        path: /{contentId}
+        method: POST
+        documentation:
+          operationId: getMyContent
+```
+
+You can refer to the `operationId` that you created.
+
+You can read more about [links](https://swagger.io/docs/specification/links/) on the swagger.io site and in the [OpenAPI](https://spec.openapis.org/oas/v3.0.3#link-object) specification. They don't seem widely supported just yet, but perhaps they'll improve your documentation.
+
 ##### `responseHeaders`
 
 The `responseHeaders` property allows you to define the headers expected in a HTTP Response of the function event. This should only contain a description and a schema, which must be a JSON schema (inline, file or externally hosted).
@@ -882,7 +937,7 @@ This will set the `Cache-Control` Response Header to have a value of "no-store"
 
 ## Example configuration
 
-Please view the example [serverless.yml](test/serverless-tests/serverless%202/serverless.yml).
+Please view the example [serverless.yml](test/serverless-tests/best/serverless.yml).
 
 ## Notes on schemas
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.72",
+  "version": "0.0.80",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [

package.json

@@ -34,6 +34,9 @@ class DefinitionGenerator {
 
     this.schemaHandler = new SchemaHandler(serverless, this.openAPI);
 
+    this.operationIdMap = {};
+    this.functionMap = {};
+
     this.operationIds = [];
     this.schemaIDs = [];
 
@@ -92,6 +95,8 @@ class DefinitionGenerator {
       throw err;
     });
 
+    this.cleanupLinks();
+
     if (this.serverless.service.custom.documentation.servers) {
       const servers = this.createServers(
         this.serverless.service.custom.documentation.servers
@@ -156,6 +161,7 @@ class DefinitionGenerator {
   async createPaths() {
     const paths = {};
     const httpFunctions = this.getHTTPFunctions();
+
     for (const httpFunction of httpFunctions) {
       for (const event of httpFunction.event) {
         if (event?.http?.documentation || event?.httpApi?.documentation) {
@@ -164,21 +170,11 @@ class DefinitionGenerator {
             event?.http?.documentation || event?.httpApi?.documentation;
 
           this.currentFunctionName = httpFunction.functionInfo.name;
-
-          let opId;
-          if (
-            this.operationIds.includes(httpFunction.functionInfo.name) === false
-          ) {
-            opId = httpFunction.functionInfo.name;
-            this.operationIds.push(opId);
-          } else {
-            opId = `${httpFunction.functionInfo.name}-${uuid()}`;
-          }
+          this.operationName = httpFunction.operationName;
 
           const path = await this.createOperationObject(
             event?.http?.method || event?.httpApi?.method,
-            documentation,
-            opId
+            documentation
           ).catch((err) => {
             throw err;
           });
@@ -282,11 +278,25 @@ class DefinitionGenerator {
     Object.assign(this.openAPI, { tags: tags });
   }
 
-  async createOperationObject(method, documentation, name = uuid()) {
+  async createOperationObject(method, documentation) {
+    let operationId = documentation?.operationId || this.operationName;
+    if (this.operationIds.includes(operationId)) {
+      operationId += `-${uuid()}`;
+    }
+
+    const arr = this.functionMap[this.operationName];
+    arr.push(operationId);
+    this.functionMap[this.operationName] = arr;
+
+    this.operationIds.push(operationId);
+    Object.assign(this.operationIdMap, {
+      [operationId]: this.operationName,
+    });
+
     const obj = {
       summary: documentation.summary || "",
       description: documentation.description || "",
-      operationId: documentation.operationId || name,
+      operationId: operationId,
       parameters: [],
       tags: documentation.tags || [],
     };
@@ -472,6 +482,10 @@ class DefinitionGenerator {
         }
       }
 
+      if (response.links) {
+        obj.links = this.createLinks(response.links);
+      }
+
       Object.assign(responses, { [response.statusCode]: obj });
     }
 
@@ -691,6 +705,36 @@ class DefinitionGenerator {
     return params;
   }
 
+  createLinks(links) {
+    const linksObj = {};
+    for (const link in links) {
+      const linkObj = links[link];
+      const obj = {};
+
+      obj.operationId = linkObj.operation;
+
+      if (linkObj.description) {
+        obj.description = linkObj.description;
+      }
+
+      if (linkObj.server) {
+        obj.server = this.createServers(linkObj.server);
+      }
+
+      if (linkObj.parameters) {
+        obj.parameters = linkObj.parameters;
+      }
+
+      if (linkObj.requestBody) {
+        obj.requestBody = linkObj.requestBody;
+      }
+
+      Object.assign(linksObj, { [link]: obj });
+    }
+
+    return linksObj;
+  }
+
   addToComponents(type, schema, name) {
     const schemaObj = {
       [name]: schema,
@@ -863,6 +907,27 @@ class DefinitionGenerator {
     return examplesObj;
   }
 
+  cleanupLinks() {
+    for (const path of Object.keys(this.openAPI.paths)) {
+      for (const [name, value] of Object.entries(this.openAPI.paths[path])) {
+        for (const [statusCode, responseObj] of Object.entries(
+          value.responses
+        )) {
+          if (responseObj.links) {
+            for (const [linkName, linkObj] of Object.entries(
+              responseObj.links
+            )) {
+              const opId = linkObj.operationId;
+              if (this.functionMap[opId]) {
+                linkObj.operationId = this.functionMap[opId][0];
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
   getHTTPFunctions() {
     const isHttpFunction = (funcType) => {
       const keys = Object.keys(funcType);
@@ -883,7 +948,16 @@ class DefinitionGenerator {
       })
       .map((functionType) => {
         const event = functionType.events.filter(isHttpFunction);
+        const name = functionType.name.split(
+          `${this.serverless.service.service}-${this.serverless.service.provider.stage}-`
+        )[1];
+
+        Object.assign(this.functionMap, {
+          [name]: [],
+        });
+
         return {
+          operationName: name,
           functionInfo: functionType,
           handler: functionType.handler,
           name: functionType.name,

src/definitionGenerator.js

@@ -0,0 +1,16 @@
+{
+  "name": "serverless-3",
+  "version": "0.0.14",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "generate": "npx serverless openapi generate -o openapi.json -f json -a 3.0.3"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "serverless": "^3.21.0"
+  }
+}