do our swagger/openapi definitions support auto-generation of api clients?

[judell]

I spoke to Matthew Lincoln, the author of https://github.com/mdlincoln/hypothesisr, and with a user of that wrapper who asked about whether hypothesisr might be submitted to rOpenSci. Matthew says he's not doing anything further with hypothesisr and suggests a more modern R-based Hypothesis client could be made by pointing https://github.com/bergant/rapiclient at https://h.readthedocs.io/en/latest/api-reference/hypothesis-v1.yaml.

Here's what I found in R:

> library(rapiclient)
> 
> h_api = get_api(url= "https://h.readthedocs.io/en/latest/api-reference/hypothesis-v1.yaml")
Error in parse_con(txt, bigint_as_char) : 
  lexical error: invalid char in json text.

Output from a validator: http://online.swagger.io/validator/debug?url=https://h.readthedocs.io/en/latest/api-reference/hypothesis-v1.yaml

Do we expect this should work, and should be a way to create a Hypothesis API client for R?

[judell]

@robertknight pointed out that the tools are expecting JSON. I used http://convertjson.com/yaml-to-json.htm to convert. Now:

> h_api = get_api(url= "https://jonudell.info/h/hypothesis-api.json")
Warning message:
In get_api(url = "https://jonudell.info/h/hypothesis-api.json") :
  Missing Swagger Specification version

[judell]

I'll dig into this a bit more and report back. It'd be very cool if this can work, not only for R but for other languages since I'm guessing there are rapiclient equivalents.

[judell]

Here's what editor.swagger.io finds:

[judell]

I got it working by downgrading to swagger 2.0 and tweaking the server path (https://jonudell.info/h/hypothesis-api.json).

> h_api = get_api(url= "https://jonudell.info/h/hypothesis-api.json")
> operations = get_operations(h_api)
> response =  operations$Search_for_annotations()

Response [https://hypothes.is/api/search]
  Date: 2019-08-30 17:22
  Status: 200
  Content-Type: application/json
  Size: 35.1 kB

> str(httr::content(response))

List of 2
 $ total: int 863207
 $ rows :List of 20
  ..$ :List of 15
  .. ..$ id         : chr "kRFDXMtIEem0FUPlO7zU3w"
  .. ..$ created    : chr "2019-08-30T17:06:54.205593+00:00"
  .. ..$ updated    : chr "2019-08-30T17:06:54.205593+00:00"
  .. ..$ user       : chr "acct:corecomps@hypothes.is"
  .. ..$ uri        : chr "http://docs.recoverhealth.org/home/singlelogin%3Fr%3D%252Fhome%252F"
  .. ..$ text       : chr "Testing"
  .. ..$ tags       : list()
  .. ..$ group      : chr "__world__"
  .. ..$ permissions:List of 4
  .. .. ..$ read  :List of 1
  .. .. .. ..$ : chr "group:__world__"
  .. .. ..$ admin :List of 1
  .. .. .. ..$ : chr "acct:corecomps@hypothes.is"
  .. .. ..$ update:List of 1
  .. .. .. ..$ : chr "acct:corecomps@hypothes.is"
  .. .. ..$ delete:List of 1

Pretty cool.

I don't think auth will work without more backporting than I want to attempt right now. For the original scenario that prompted this issue, the older R client may have to suffice. But it's nice to see that autogeneration of H API clients is indeed possible.

[judell]

I also tried a more modern approach, https://openapi-generator.tech.

Result:

>npx openapi-generator generate -i hypothesis.yaml -g python -o .
[main] WARN  io.swagger.v3.parser.OpenAPIV3Parser - Exception while reading:
java.lang.RuntimeException: Unable to load RELATIVE ref: ./schemas/errors.yaml