Additionnal response and OpenAPI generation

fberrez commented 5 years ago

go version: go version go1.11.1 darwin/amd64
fizz version (or commit ref): d320b2d

Description

What ?

The OpenAPI generation generates a bad syntax for a path which have an additionnal response with the status code not found (404). Instead of having 404 in the OpenAPI JSON structure, we have a Ɣ. See below.

How ?

Here is my code for a router:

// Defines groups of routes
    lightsGroup := f.Group("/lights", "Lights", "")

// Defines Lights group's routes
    lightsGroup.GET("/", []fizz.OperationOption{
        fizz.Summary("Gets a list of lights corresponding to the selector."),
        fizz.Description("Returns a list of lights with their informations."),
        fizz.Response(string(http.StatusNotFound), "cannot find lights corresponding to the selector.", nil, nil),
    }, tonic.Handler(api.getDevices, http.StatusOK))

Here is the OpenAPI generation for this path:

{
   "paths":{
      "/lights/":{
         "get":{
            "tags":[
               "Lights"
            ],
            "summary":"Gets a list of lights corresponding to the selector.",
            "description":"Returns a list of lights with their information.",
            "operationId":"getDevices)-fm",
            "parameters":[
               {
                  "name":"selector",
                  "in":"query",
                  "description":"The selector to limit which lights are controlled. More informations about format here: https://api.developer.lifx.com/docs/selectors",
                  "schema":{
                     "type":"string",
                     "description":"The selector to limit which lights are controlled. More informations about format here: https://api.developer.lifx.com/docs/selectors",
                     "default":"all"
                  }
               }
            ],
            "responses":{
               "200":{
                  "description":"OK",
                  "content":{
                     "application/json":{
                        "schema":{
                           "type":"array",
                           "items":{
                              "$ref":"#/components/schemas/LifxLifx"
                           }
                        }
                     }
                  }
               },
               "Ɣ":{
                  "description":"cannot find lights corresponding to the selector."
               }
            }
         }
      },
...

You can see "Ɣ"instead of "404".

wI2L commented 5 years ago

404 is the ASCII code for the Unicode Latin Small Letter Gamma rune (see full table here). The issue you are encountering isn't due to Fizz, but rather the conversion of the http.StatusNotFound constant to string in your code.

I have reproduced the behaviour here: https://play.golang.org/p/dkTngug0pyT

I recommend using a string directly as an argument of fizz.Response, or convert it beforehand with strconv.Atoi.

You can find here the spec about responses and the field pattern. I think it could be useful to add an advanced check during the spec generation to ensure that the given code is valid per the spec.

Last thing, give a look at the function fizz.Errors that returns all non-critical errors that occurs during the generation of the spec. You would have catched the error returned by setOperationResponse when it convert the code to an integer with strconv.Atoi.

Feel free to reopen if need be.

wI2L commented 5 years ago

fberrez commented 5 years ago

I really appreciate your documented answer. Thank you, I learnt something new today! 👍

wI2L / fizz