openapi support

[dr3s]

it would be great to see the client natively support openapi json/yaml, so rest apis that are already documented can be accessed more easily.

[hazbo]

I've had a quick look into this, and this is something I'd really like to get off the ground. It'd be nice to support a few different types of configs, support for Postman and Insomnia etc...

I'm going to keep this issue open and will keep it updated with any decisions made regarding this. In the meantime if you have any further ideas about how this could work, feel free to leave comments on this issue.

[AdvancedHacker101]

I think this could work 2 ways:

1. Replace the current file format describing requests/responses, and replace them with the Open API ones.
   Pro: Files would follow a standard and it would become more easy to create/get files for a service
   Con: In this case the interpreter for the files need to be re-written and it would require the program to understand both JSON and YAML formats, because the specification support both of them.
2. Write a converter for the existing Open API documents
   Pro: This would be a shorter solution, because then there's no need to re-write the file interpreter, and would still grant access to services using the Open API specification
   Con: This is a "hack", in this case we aren't following the specification, and we would need to re-convert files with every new major version of the specification

TL;DR: I think option 1 is better in the long run, but option 2 is quicker and shorter even if it's a hack

[hazbo]

@AdvancedHacker101 hey there, thanks for weighing in on this! I've also had a think regarding both of these options. Currently leaning towards a longterm way of implementing option 2. This is because if it is abstracted well, and we are able to transform OpenAPI -> what's there now, we'd also be able to look at supporting any other configs out there, i.e. PostMan and Insomina.

I'm not trying to reinvent the wheel with a new standard as such, but the current spec has been thought out in such a way that it can be extended to do some really cool things. For example, right now we currently have a single kind of resource, which is a request. I'd soon like to add a new resource type to the project called test, so that users can write config to go through and test every endpoint of an application.

So in short, if I am able to come up with a way for option 2 that is not a hack, that would be great.

What do you think about this?

[AdvancedHacker101]

For the other specs (PostMan, Insomnia) we would need to write a converter anyways, if we want to support them, so yeah, then option 2 is the better choice here.
The next thing to think about is how this converter application will integrate with the packages repo of the application, for example if a user converts an API it could be pushed automatically to the packages repo or it could be controlled by a flag like --push or --no-push or we don't do this at all and wait for the users to manually share their converted API

[hazbo]

@AdvancedHacker101 yeah this is a really good point. An idea I had was to sorta just convert the PostMan, Insomnia etc... at runtime, and then simply let it run normally.

So at this point, in memory, it's all represented as httpu's request resource. However, how do you feel about there being an export or save option, to actually write the JSON transformation?

So something like: httpu new my-insomnia-config --save

As of right now, there is no --push functionality, as the canonical packages repo is read-only. But I love the idea of being able to do that (perhaps a separate issue). And on that subject, we should allow the user to specify or use a different packages repo, much like homebrew uses taps.

Do you have any thoughts regarding how the cli api / commands / options may look for the transform stuff? (What I have written above was just off the top of my head)