search

cloudflare / doca

A CLI tool that scaffolds API documentation based on JSON HyperSchemas.
BSD 3-Clause "New" or "Revised" License
228 stars 36 forks source link

Group actions on the same object / endpoint #7

Closed Relequestual closed 6 years ago

Relequestual commented 7 years ago

Having spent a while comparing doca with api-console, some things look rather nice about it.

Example page (may take a while to load) https://anypoint.mulesoft.com/apiplatform/popular/#/portals/organizations/52560d3f-c37a-409d-9887-79e0a9a9ecff/apis/5502/versions/5487/pages/30295

handrews commented 7 years ago

@Relequestual what in particular do you like about api-console's grouping? I like that it is easier to see what actions are available at a glance, but dislike the emphasis on the URI template and feel that the tabbed nature still makes it difficult to grasp it all at once. They've crammed a lot of information into each "card" but it's hard to recombine that into a holistic view.

Relequestual commented 7 years ago

It's easier to see at a glance which parts of CRUD are available for each object. I wouldn't say I was interested in the URI emphasis. With Doca, I can't tell what actions I can perform on an object at the same time.

The API I'm building will not have lots of routes with the same base, unlike the example. The routes are rather limited at current. I guess it would be much less of an issue if the left hand side menu bar was floating (As I raied for #8 )

handrews commented 7 years ago

@Relequestual thanks! Yes, I want to rework the presentation to focus primarily on the representation of the resource, and then show HTTP method support in relation to that. Currently the main representation is hidden under a button and the method requests/responses are laid out sequentially which makes them hard to see as a whole.

I also want Doca to present the minimum necessary documentation. Both its current view and api-console's view spend a lot of effort on things that don't need repeating. For example, even when the request and/or response is the representation, Doca repeats the representation spec each time. That takes up a lot of space without telling us anything new. On the other hand, api-console lists a whole bunch of error responses even when they just repeat the definition from the HTTP spec. While we might want to indicate which errors are possible in general, we shouldn't need to document specific error responses unless they carry a specific error representation conveying additional information.

handrews commented 6 years ago

This set of packages is being deprecated in favor of the JSON Schema Tools monorepo. Contributions are still welcome here but most work will be done on the new packages.

The new UI is still being designed, but hopefully this should be handled in it. Feel free to file at cloudflare/json-schema-tools if you want to track this specifically.