Skip to content

Swagger integration improvements #113

@fogine

Description

@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?

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions