VL.OpenAPI

wip
1

Bonsoir,

This is to show you VL.OpenAPI, a plugin that automagically generates nodes from an OpenAPI description. “Was ist OpenAPI”, you ask? Read along!

OpenAPI is an open format that describes REST APIs in JSON/YAML format. Basically, it lists all the queries, parameters, descriptions and responses that a REST API has to offer (and much more : data structures, authentication methods, and so on).

Basically the plugin does that : it looks at this OpenAPI description, and for all the possible queries gives you a node with the correct pins, description and all. You just specify the URL to get to the OpenAPI description in a text file next to your patch (à la VL.RunwayML), and the factory does the rest.

You might remember the VL.Postman thing that was shown at a previous meetup. @velcrome mentioned this OpenAPI standard that felt like a better choice because it would allow to cover more cases (though the Postman thing could still be useful for other very specific cases… but the openness of OpenAPI is more appealing :p).

So if you want to have a look at it (beware, it’s still at an early phase and not-that-easy to use - i.e no nuget yet), here it is :

Instructions are available in the README.

openapi
This is a node that was generated by the factory, yeepee!

Current status :

  • Tested against a Directus instance (it exposes an OpenAPI description, thanks for that @sebl!) for convenience because I suck at webdev
  • Reads the OpenAPI spec and generates nodes for each path it contains
  • Retrieves descriptions for pins and nodes
  • Only supported auth mechanism is via query parameters for now

Next steps :

  • What shall we do with the result of the queries? For now we simply output the raw JSON, but since the spec includes a description of the data format, could we generate datatypes on the fly and return objects instead? That sounds cool, but as you can see in the gif above (which shows interaction with a Directus instance), the user can also customize specify which fields they want to see in the response. If you’re querying items from a relational field, you can even go backward to parent fields… which makes the output format kinda unpredictable.
  • Support for multiple authentication mechanisms. Guess that would need an editor extension for more advanced setups.
  • C# code might not be the most elegant for now :x

So here it is, have a look at it, test it with your OpenAPI stuff and please shout here or on the repo.

If anybody’s interested to join forces for the development, please shout as well :]

thanks and enjoyyyy

6 Likes