-
Notifications
You must be signed in to change notification settings - Fork 327
Description
@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 callhttp://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 trimmedsummary
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
- PUT
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?