How to use serverless-openapi-documentation with serverless Typescript template? #41

Activity

1. prabhanjansyn commented on Dec 4, 2020

   

   prabhanjansyn

   on Dec 4, 2020

   Last edited by prabhanjansyn

   More actions

   I'd love to know it as well
2. chrisrabe commented on Apr 27, 2022

   

   chrisrabe

   on Apr 27, 2022

   More actions

   Oh jeez. It seems to be over a year since this issue has been opened and no resolution. I hope I'm not necro-posting.

   I figured out how to somewhat get serverless-openapi-documentation working with the serverless TS template. I say "somewhat" because there's a few kinks that I found when using this plugin but it's a good place to start for anyone else looking into this.

   Initial Configuration

   For initial configurations, I created a new typescript file called docs. Inside it has the following contents

   const docs = {
     version: '1',
     title: 'Some title',
     description: 'My API description',
     models: [ ... ]
   };
   
   export default docs;
   

   This is then imported into the "custom" property of the serverless template like so:

   import docs from "./docs";
   
   ...
   custom: {
     documentation: docs
     ...
   ...
   

   Then added the serverless-openapi-documentation into my list of plugins.

   Setting up functions

   To set up functions, I separated out the functions configuration in its own typescript file and assigned it to a constant like so:

   export const functions: any = {
     myFunction: {
       ...,
       documentation: {
         ...
       }
     }
   }
   

   After that, I then imported this separate file into my main serverless template like so:

   import {functions} from "./functions"
   
   const serverlessConfiguration = {
     ...,
     functions,
     ...
   }
   

   The problem now

   When running serverless openapi generate, it creates an openapi.yml that contains documentation about my functions, models and response types but it can't seem to translate pathParams or queryParams properly.

   I specified them in my documentation like so:

               pathParams: [
                 {
                   name: 'id',
                   description: 'Hotel ID to retrieve',
                   schema: {
                     type: 'string'
                   }
                 }
               ],
   

   But it doesn't seem to be included in the openapi.yml output. Am I missing anything here?

   👍React with 👍1Reacted by QJ Li