API fails swagger validation

[stevegt]

Either I'm doing something wrong or the API (as of d94472e) is not currently emitting swagger-compliant JSON. This is causing problems when trying to use various parsers and client generators/libraries to create gitea clients, as they try to validate when parsing. The error messages I'm getting vary by library, but as a simple check, try this:

$ curl https://try.gitea.io/swagger.v1.json > swagger.v1.json 
$ npm install -g swagger-cli
$ swagger-cli validate swagger.v1.json 
Swagger schema validation failed. 
  Missing required property: description at #/responses/parameterBodies
 
JSON_OBJECT_VALIDATION_FAILED

I've tried other parsers and validators, both CLI and online, and get different errors; still trying to figure out if there's any common denominator other than PEBCAK. Anyone else seeing this?

[stevegt]

I'm sure many here already know this, but I finally realized that we're also getting a validation error at the bottom of https://try.gitea.io/api/swagger. If you click on the little red "Error" badge at the bottom of the page, you get a set of errors from swagger.io's own validator:

https://online.swagger.io/validator/debug?url=https://try.gitea.io/swagger.v1.json

[sapk]

Yes, this is mostly some description missing and few corner case like /markdown/raw.

This could maybe easely fix by updating comments that are used to generate the json with https://github.com/go-swagger/go-swagger

[stevegt]

Starting work on these. For future reference, a quick way to get an easy-to-read list of errors from the swagger.io online validator is:

curl -X POST -d @public/swagger.v1.json -H 'Content-Type:application/json' http://online.swagger.io/validator/debug | json2yaml

[stevegt]

So far it appears that at least some of these are more than just missing/wrong comments -- unless I'm misunderstanding something, the /responses/* errors are related to missing code. It's been a couple of days since I had a chance to look, but iirc those comments need to point at code that I couldn't find and may not exist yet. It could be that just adding a description field will make the validator happy, but I haven't had a chance to try that yet.

[sapk]

Some comments especially responses are under https://github.com/go-gitea/go-sdk that is under vendor/ in gitea repo.

[stevegt]

This local command provides a more comprehensive error list than the swagger.io online validator command I mention above, and the output is equally easy to read:

swagger validate public/swagger.v1.json

[MikeRalphson]

Thanks for the fixes - the definition still contains some errors:

  "security": [
    {
      "BasicAuth": [
        "[]"
      ]
    },
    {
      "Token": [
        "[]"
      ]
    },
    {
      "AccessToken": [
        "[]"
      ]
    },
    {
      "AuthorizationHeaderToken": [
        "[]"
      ]
    }
  ]

The scopes arrays themselves should be empty, they should not contain strings with the value [].

[sapk]

@MikeRalphson this should be fixed in #4236
It was not catched by the validator that we used.

[MikeRalphson]

@sapk The fix in #4236 LGTM. Thanks.