feat(cli): add comments for generated methods from openapi

Author: raymondfeng

packages/cli/generators/openapi/spec-helper.js

@@ -149,6 +149,7 @@ function getMethodName(opSpec) {
  */
 function buildMethodSpec(controllerSpec, op, options) {
   const methodName = getMethodName(op.spec);
+  const comments = [];
   let args = [];
   const parameters = op.spec.parameters;
   // Keep track of param names to avoid duplicates
@@ -163,6 +164,7 @@ function buildMethodSpec(controllerSpec, op, options) {
       }
       const pType = mapSchemaType(p.schema, options);
       addImportsForType(pType);
+      comments.push(`@param ${name} ${p.description || ''}`);
       return `@param({name: '${p.name}', in: '${p.in}'}) ${name}: ${
         pType.signature
       }`;
@@ -195,6 +197,9 @@ function buildMethodSpec(controllerSpec, op, options) {
     args.unshift(
       `@requestBody(${bodySpec}) ${bodyParam}: ${bodyType.signature}`,
     );
+    comments.unshift(
+      `@param ${bodyName} ${op.spec.requestBody.description || ''}`,
+    );
   }
   let returnType = {signature: 'any'};
   const responses = op.spec.responses;
@@ -212,20 +217,24 @@ function buildMethodSpec(controllerSpec, op, options) {
      */
     for (const code in responses) {
       if (isExtension(code)) continue;
-      if (code !== '200') continue;
+      if (code !== '200' && code !== '201') continue;
       const content = responses[code].content;
       const jsonType = content && content['application/json'];
       if (jsonType && jsonType.schema) {
         returnType = mapSchemaType(jsonType.schema, options);
         addImportsForType(returnType);
+        comments.push(`@returns ${responses[code].description || ''}`);
+        break;
       }
     }
   }
   const signature = `async ${methodName}(${args.join(', ')}): Promise<${
     returnType.signature
   }>`;
+  comments.unshift(op.spec.description || '', '\n');
   const methodSpec = {
     description: op.spec.description,
+    comments,
     decoration: `@operation('${op.verb}', '${op.path}')`,
     signature,
   };

packages/cli/generators/openapi/templates/src/controllers/controller-template.ts.ejs

@@ -18,7 +18,9 @@ export class <%- className %> {
 
   <%_ for (const m of methods) { -%>
   /**
-   * <%- m.description %>
+  <%_ for (const c of m.comments) { -%>
+   * <%- c %>
+  <%_ } -%>
    */
   <%- m.decoration %>
   <%- m.signature %> {

packages/cli/test/unit/openapi/controller-spec.unit.js

@@ -18,36 +18,56 @@ describe('openapi to controllers/models', () => {
     expect(customerSepc.controllerSpecs).to.eql([
       {
         tag: 'Customer',
-        className: 'CustomerController',
         description: 'Customer resource',
+        className: 'CustomerController',
         imports: ["import {Customer} from '../models/customer.model';"],
         methods: [
           {
             description: 'Returns all customers',
+            comments: [
+              'Returns all customers',
+              '\n',
+              '@param _if if condition',
+              '@param limit maximum number of results to return',
+              '@param accessToken Access token',
+              '@returns customer response',
+            ],
             decoration: "@operation('get', '/customers')",
             signature:
               "async getCustomers(@param({name: 'if', in: 'query'}) _if: " +
               "string[], @param({name: 'limit', in: 'query'}) limit: number, " +
-              "@param({name: 'access-token', in: 'query'}) " +
-              'accessToken: string): ' +
-              'Promise<Customer[]>',
+              "@param({name: 'access-token', in: 'query'}) accessToken: " +
+              'string): Promise<Customer[]>',
           },
           {
             description: 'Creates a new customer',
+            comments: [
+              'Creates a new customer',
+              '\n',
+              '@param body Customer to add',
+              '@param accessToken Access token',
+              '@returns customer response',
+            ],
             decoration: "@operation('post', '/customers')",
             signature:
               'async createCustomer(@requestBody() body: Customer, ' +
-              "@param({name: 'access-token', " +
-              "in: 'query'}) accessToken: string): Promise<Customer>",
+              "@param({name: 'access-token', in: 'query'}) accessToken: " +
+              'string): Promise<Customer>',
           },
           {
             description: 'Returns a customer based on a single ID',
+            comments: [
+              'Returns a customer based on a single ID',
+              '\n',
+              '@param id ID of customer to fetch',
+              '@returns customer response',
+            ],
             decoration: "@operation('get', '/customers/{id}')",
-            implementation:
-              "return {id: id, 'first-name': 'John', last-name: 'Smith'};",
             signature:
               "async findCustomerById(@param({name: 'id', in: 'path'}) " +
               'id: number): Promise<Customer>',
+            implementation:
+              "return {id: id, 'first-name': 'John', last-name: 'Smith'};",
           },
         ],
       },

packages/cli/test/unit/openapi/schema-model.unit.js

@@ -210,8 +210,8 @@ describe('schema to model', () => {
         import: "import {Address} from './address.model';",
         kind: 'class',
         declaration:
-          '{\n  street?: string;\n  city?: string;\n  state?: string;\n' +
-          '  zipCode?: string;\n}',
+          '{\n  street?: string;\n  city?: string;\n  state?: string;\n  ' +
+          'zipCode?: string;\n}',
         signature: 'Address',
       },
       {
@@ -248,8 +248,8 @@ describe('schema to model', () => {
         import: "import {Customer} from './customer.model';",
         kind: 'class',
         declaration:
-          "{\n  id: number;\n  'first-name'?: string;\n  " +
-          "'last-name'?: Name;\n  addresses?: Address[];\n}",
+          "{\n  id: number;\n  'first-name'?: string;\n  'last-name'?: " +
+          'Name;\n  addresses?: Address[];\n}',
         signature: 'Customer',
       },
     ]);