Swagger integration improvements

[fogine]

@eliangcs , Thank you for your good job with initial integration with swagger specs. I had time to put swagger feature into practice and think there could be made several improvements which would increase overall usability as swagger specifications contain much more information that could be displayed to an user.
The following are general ideas how we could improve swagger integration.

• Make use of host & basePath swagger root properties. Basically call http://localhost:8000> cd $host + $basePath by default .

• Autocompletion of ls & cd cmds is quite handy as it is. However, the "Endpoint" static value is currently showed everywhere no matter whether current path is an actual endpoint or just part of one or more endpoints. Furthermore, useful would be to show trimmed summary string value in autocompletion popup when we want to initiate the request. Consider the following example:

  http://localhost:8000/users/fogine/apps> post

  When I type the request method (post), I'd get "Creates new app" instead of current "POST request" autocompletion value. Also we could show autocompletion of url segments in case of inline endpoint definition: Example:

http://localhost:8000/users/> post fogine/apps

while typing the "fogine/apps" path segment, it'd show autocompletion of possible url segments and for the last url segment (apps) I could get completion value of "Creates new app" string. I think this would really improve user experience although I haven't considered possible implementation issues so far.

• The ls command could give so much more information to an user. Consider the following list of endpoints that web service implements:
  • PUT /users/{username}
  • POST /users/{username}
  • PUT /users/{username}/avatar

Now in http-prompt I'd just show the data:

http://localhost:8000> ls

   POST  /users/{username}             Creates an user
   PUT   /users/{username}             Updates an user
   PUT   /users/{username}/avatar      Upload avatar

http://localhost:8000> ls users

   POST  {username}             Creates an user
   PUT   {username}             Updates an user
   PUT   {username}/avatar      Upload avatar

Here, sample endpoints are rather simple but for more complicated routes, the summary and possible request methods of given endpoint provide very useful info. There is more information to show like endpoint tags, operationId. Table heading and columns could be configurable...
ls command could also work with operationId swagger option as an endpoint which implements more than one request method can't uniquely identify itself. When an user would ls an actual endpoint, eg:

http://localhost:8000> ls urlOperationIdOrUniqueUrl

we could display detailed endpoint information, like route description, response http codes, for request parameters - parameter type, information about whether a parameter is required or not etc...

To conclude where I'm heading with this, the idea is to be able to use http-prompt with swagger specs without a need for actually looking for information elsewhere like now it's required for more complicated web services.
Note: I haven't thought much about the actual data output formats, so that should be thought out. What do you think @eliangcs or anybody else?

[eliangcs]

@fogine sorry for late reply. Please see my feedback as follows.

Make use of $host & $basePath swagger root properties.

I thought about letting users read environment variables in http-prompt. So users can do something like --auth $USERNAME:$PASSWORD. Making use of $host and $basePath can conflict with environment variables. We should figure out a better design for this.

show trimmed summary string value in autocompletion popup

👍 for this one. Nice suggestion!

The ls command could give so much more information to a user.

This is a good feature, too! But I want ls to behave like it was in the shell environment, so let's keep ls the way it is now. And if users want to see more information (description and such), they could do ls -l, just like you would do in the shell.

[branquito]

I don't know why, but when given the specification via --spec flag, when I use http-prompt [domain] I get ls working fine, but cannot consume api because it's name-spaced under /api, and there is a basePath: "/api" in json spec file, however when I do http-prompt [domain]/api then ls and cd stop working. What might be the problem?

[my-flow]

I seem to have the same problem as @branquito. The swagger integration does not respect the basePath of the swagger spec correctly. It would be great if this could be improved.

[eliangcs]

@branquito @my-flow the basePath issue has been fixed in v0.11.2.

[alansill]

Can the input for OpenAPI specs be specified in YAML format rather than JSON/ Also, what version is supported (OpenAPI 3, I hope!)

[alansill]

Can the input for OpenAPI specs be specified in YAML format rather than JSON/ Also, what version is supported (OpenAPI 3, I hope!)

See PR#149 https://github.com/eliangcs/http-prompt/pull/149

[CrispyDrone]

Hi,

Is there any way to show the schema of the body (for POST calls) when exploring the OpenAPI spec through this feature? I've looked through the documentation but can't seem to find any information about it.

Thanks.