Added Parameters section to swagger:route

[jucardi]

Working on a company project, we have a custom version of the Swagger API which allow us to do calls to our microservices by reading the swagger documentation generated from our builds.

We use Gin for our API endpoints in our Go Microservices and unfortunately we were unable to tie the Request models to the router definitions.

I added a section in the swagger:route parser, so Parameters can be included with their properties, to easily allow adding a reference to a swagger:model for body params. Multiple parameters can be added under Parameters by simply using the + prefix when a new parameter starts. Example:

//  Create a pet based on the parameters.
//
//  Consumes:
//  - application/json
//  - application/x-protobuf
//  
//  Produces:
//  - application/json
//  - application/x-protobuf
//
//  Schemes: http, https, ws, wss
//
//  Parameters:
//  + name: request
//    in: body
//    schema: modelName
//  + name: id
//    in: path
//
//  Responses:
//    default: body:genericError
//    200: body:someResponse
//    422: body:validationError
//
//  Security:
//    api_key:
//    oauth: read, write

[houndci-bot]

exported const ParamDescriptionKey should have comment (or a comment on this block) or be unexported

[codecov]

Codecov Report

Merging #1405 into master will increase coverage by 0.47%.
The diff coverage is 96.82%.

@@            Coverage Diff             @@
##           master    #1405      +/-   ##
==========================================
+ Coverage   72.35%   72.83%   +0.47%     
==========================================
  Files          36       37       +1     
  Lines        6718     6844     +126     
==========================================
+ Hits         4861     4985     +124     
- Misses       1404     1406       +2     
  Partials      453      453

Impacted Files	Coverage Δ
generator/bindata.go	66.51% <ø> (ø)	⬆️
scan/scanner.go	73.3% <ø> (+0.45%)	⬆️
scan/routes.go	96% <100%> (+0.54%)	⬆️
scan/route_params.go	96.66% <96.66%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1643221...50345c2. Read the comment docs.

[jucardi]

I'll increase the coverage in a bit

[jucardi]

The changes in this file are just the result of a gofmt -s -w -l ., no changes in logic. If needed they could be rolled back before merging

[casualjim]

have you seen swagger:operation it allows you to specify routes but with the full swagger yaml syntax.

This PR somewhat duplicates this, but with bespoke syntax. I wonder where the type goes and some of the other validations etc that can be defined on parameters.
It's great that you figured out how to extend this 💯

[casualjim]

O I hadn't seen your response on #1404
I see you have "bigger" plans, I'm good with your remarks there would you be up for making this a bit more complete so that it covers most of the possible use cases?

[jucardi]

Hi @casualjim will do, I'll cover more validations, such as only allow the use of schemas when in:body or allow allowEmptyValue to be set only if in:query or in:formData.

Were there any other use cases you had in mind?

[casualjim]

once you have the ability to specify types you probably also want the ability to specify the validations they have to pass. Things min length, pattern, min/max etc come to mind.
Feel free to ping me on slack https://slackin.goswagger.io

[jucardi]

the constraints, you're absolutely right, I completely forgot about them, I'll work on those as well

[houndci-bot]

should omit type map[string]string from declaration of var extraData; it will be inferred from the right-hand side

[houndci-bot]

comment on exported const TypeBool should be of the form "TypeBool ..."

[jucardi]

@casualjim I added a section to parse the schema in parameters, covers max, min, maxLength, minLength, default, enum, format, it also does type assertion when using these constraints to ensure they are assigned to the right types.

Let me know if you have any observations. Thanks!