Giant Bomb OpenAPI Specification

Avatar image for drakecaiman


Forum Posts


Wiki Points



Reviews: 0

User Lists: 0

#1  Edited By drakecaiman

I've been experimenting with the API, and I thought that it might make testing easier for me if I could use some of the common API tools out there. So I wrote a parser for the API documentation and created an OpenAPI Specification document for the Giant Bomb API. I thought anyone else messing around might find it useful, so here it is!

Giant Bomb OpenAPI Specification.json

Giant Bomb OpenAPI Specification.yaml

It's still a bit of a work in progress, but I wanted to get this out and see if anyone else would find this useful and if there were any suggestions. As for my current plans:

  1. I need to make a few more revisions of the parser to make sure it is capturing all the info from the documentation page (sortable and filterable fields are not recorded yet, for example) and is correct. Eventually, I'll just have to run the parser one last time, then it will be easier to just edit the file directly.
  2. There's still a lot of missing descriptions for the various schemata, paths, and other objects that are better added after the final document is assembled. Currently there are a lot of "##" delimited tokens in the document that will be fill out with later.
  3. The properties on responses are all marked as string, another thing better filled out with the final document.
  4. I've already checked the actual output to the documentation a bit, but I still need to do a more thorough check, as well as add examples of acceptable input and output.

Other than that, I have a few things that I haven't quite figured out a plan for:

  • OpenAPI Link objects are used to describe the relationship between the output of one path to the input of another (think taking a guid from /games and using it in /games/{guid}), but there is no way I've found to describe the property of an object in an array (like in /games's response) with JSON pointers, so that might not be of value
  • I've only been able to find two responses: 200 and 401. Not sure how to find any others
  • /types is missing it's 'format' parameter on the documentation page, but I don't really have a way to find any other missing parameters on that or any other path.
  • There doesn't seem to be anyway to represent the "field:value" serialization of the sort and filter paramters, so I used a regex pattern to validate the input on them instead. It would be nice to be able to represent that as an object to limit the input with a nice UI like the format and field_list parameters, but s the use of colons is non-standard in URI queries.

Download the file, try it with SwaggerHub, Postman, Insomnia, or another similar program, and let me know how it works. I'd love to hear if this helps anyone else out.