Options

[shawngrona]

if you try and export swagger from api gateway, in the case where you have path params, swagger will give errors "Declared path parameter "[parametername]" needs to be defined within every operation in the path (missing in "options"), or moved to the path-level parameters object"

how does one define path level object in documentation with this plugin? or for that matter options documentation if you're using lambda proxy??

[sime]

@shawngrona Can't say I can help, though I am interested how your serverless.yml is defined. i.e. with an example of path pararms.

[shawngrona]

does serverless documentation support path level parameters? https://swagger.io/docs/specification/describing-parameters/#common-parameters-16

[shawngrona]

here is example of serverless.yml:

 putPreferredLanguage:
    handler: lambda/language.put
    include:
      - lib/cognito.js
    events:
      - http:
          path: app/{appId}/users/{userId}/preferredLanguage
          method: put
          cors: true
          authorizer:
            arn:  arn:aws:lambda:us-east-1:${self:custom.awsAccountId}:function:authorizer-${self:provider.stage}-appAuthorizer
            identitySource: method.request.header.Authorization
            resultTtlInSeconds: 0
          documentation:
            summary: "Set a users preferred language"
            description: "Sets the current users preferred language."
            requestBody:
              description: "The users preferred language"
            requestHeaders:
              - name: "Authorization"
                description: "JWT for the user represented by the userid"
            pathParams:
              - name: "appId"
                description: "app id"
                required: true
              - name: "userId"
                description: "user id or 'my'"
                required: true
            requestModels:
              "application/json": "UsersPreferredLanguageRequest"
            methodResponses:
              - statusCode: "204"
                responseBody:
                  description: "The preferred langauge has been set"
              - statusCode: "400"
                responseBody:
                  description: "The langauge provided is not supported. en and es are the only two valid options"
                responseModels:
                  "application/json": "UsersErrorResponse"
              - statusCode: "500"
                responseBody:
                  description: "An error occured while interfacing with AWS resources"

[shawngrona]

heres what you get from api gateway swagger export on the same:

  '/app/{appId}/users/{userId}/preferredLanguage':
   put:
      summary: Set a users preferred language
      description: Sets the current users preferred language.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: appId
          in: path
          required: true
          type: string
        - name: userId
          in: path
          required: true
          type: string
        - name: Authorization
          in: header
          description: JWT for the user represented by the userid
          required: false
          type: string
        - in: body
          name: UsersPreferredLanguageRequest
          description: The users preferred language
          required: true
          schema:
            $ref: '#/definitions/UsersPreferredLanguageRequest'
      responses:
        '204':
          description: 204 response
        '400':
          description: 400 response
          schema:
            $ref: '#/definitions/UsersErrorResponse'
        '500':
          description: 500 response
      security:
        - appAuthorizer: []
    options:
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              type: string
            Access-Control-Allow-Methods:
              type: string
            Access-Control-Allow-Credentials:
              type: string
            Access-Control-Allow-Headers:
              type: string

note how the options are missing the path parameter? if you put this into a swagger editor then it barks about the path parameters missing in options methods

[shawngrona]

or is there some way to exclude options when exporting a swagger document? its really not necessary for us in the scope of providing documentation to our app developers

[pig800509]

@shawngrona Just remove options section , in /example there is "download-swagger-json.sh"，add these code into .sh :

bash -c "node ./rebuildJSON.js"

and this is my rebuildJSON.js

var jsonfile = require('jsonfile')
var file = './swagger.json'
jsonfile.readFile(file, function(err, obj) {
    if (err) {
        console.error(err);
    } else {
        var result = JSON.parse(JSON.stringify(obj, function(key, value) {
            return key !== 'options' ? value : undefined;
        }));
        jsonfile.writeFile(file, result, function(err) {
            err ? console.error(err) : console.log("swagger.json exported successfully.");
        })
    }
})

[strepto42]

Be nice to get this one fixed... Meanwhile thank you for the snippet above

[research-scife]

Is this being worked on ?

[federico-dobal]

It would be great to have if fixed, however it is fair to mention that the script provided helps a lot!

Thanks!

[s1mrankaur]

please fix it

[mscannjr]

Yes please fix it already. It has been a problem for YEARS now.

[utsav1810]

When can we expect the fix?

[rivernews]

It would be great to be able to not having the OPTION endpoints automatically included when exporting the Swagger doc from API Gateway.

This is probably another issue, but the tags for each path are missing for the exported Swagger. We use Swagger integration to define the API paths and have tags defined for better grouping. But the exported Swagger stripped them off. It's a pain having to write another tool to post-process the exported Swagger file..