temando / serverless-openapi-documentation

Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration
MIT License
93 stars 127 forks source link

params being ignored #32

Open jkon opened 5 years ago

jkon commented 5 years ago

Pretty sure this is an issue with my config, but I need some help. I have added a bit of documentation to some of my endpoints, but none of the parameters seem to be getting added to the openapi spec created when I run the generator. Here is an example of an endpoint's documentation:

getDailyHistoricalData:
    summary: "Get Daily Historical Data"
    description: "Returns at least 60 days worth of historical data on the requested security"
    requestBody:
      description: "None"
    queryParams:
      - name: "identifier"
        required: true
        description: "Identifier of the security to query daily data on"
        schema:
          type: "string"

The summary and description are the the only things making it through to the generated json file. This is the command I am using: serverless openapi generate -o '../docs/historical.json' -f json Any idea why I am not getting the queryParams or the requestBody. Here is what the output for that endpoint looks like:

"/daily": {
      "get": {
        "operationId": "getDailyHistoricalData",
        "summary": "Get Daily Historical Data",
        "description": "Returns at least 60 days worth of historical data on the requested security",
        "responses": {}
      }
    }

thanks

jkon commented 5 years ago

I was looking through the code and I found the problem. In the getOperationFromConfig, in the DefinitionGenerator class, for requestBody and parameters you check if the operationObject has the two, but it should really be checking whether documentationConfig has those two. Here is what you have:

    if (operationObj.requestBody) {
      operationObj.requestBody = this.getRequestBodiesFromConfig(documentationConfig);
    }

    if (operationObj.parameters) {
      operationObj.parameters = this.getParametersFromConfig(documentationConfig);
    }

It should be

    if (documentationConfig.requestBody) {
         operationObj.requestBody = this.getRequestBodiesFromConfig(documentationConfig);
    }
    if (documentationConfig.parameters) {
        operationObj.parameters = this.getParametersFromConfig(documentationConfig);
    }

Is this something you can fix soon?

jkon commented 5 years ago

After looking at this a little more, the check for documentationConfig.parameters is also wrong. when there are no pathParams, queryParams, etc, the script works fine if you don't check. I tried it out by modifying the js file in the installed package. I also tried forking the repo and making my own version, but I can't get the build to work for some reason. If someone could fix this soon, it would be really helpful

jhaagmans commented 5 years ago

Unfortunately, this project is dead and broken. PR #27 fixes this, but was rejected because the maintainers don't use this plugin anymore. You could patch your local plugin with the changes in #27 and things should be working again, although that might not be a convenient solution for everyone.

jkon commented 5 years ago

Thanks for letting me know the project is dead. I ended up forming it and fixing it myself. I also added support for x-code-samples. Problem is that I couldn’t figure out how publish to npm with a different name and get it to work with serverless, so I ended up just building the project and hosting the built files as a separate repo that I point to in my package.json