Idea: Generate an endpoint-specific test console

[timwis]

Hey guys, looking forward to seeing this documentation grow! I had an idea a few months ago that might align with your efforts here in making the ArcGIS REST API easier to use.

Tools like swagger generate test consoles based on yaml or json configuration (demo). Basically, the idea is to generate this standards-compliant yaml from the geoservice metadata api. It would pull in all the feature services, and potentially even the field names and types. This could be done on a schedule, by the arcgis server (in future versions), or even on the client. With the configuration file that's produced, you could use something like swagger to generate a test console that's simplified, demonstrates what result a query produced, and lets you copy & paste the query.

We've implemented swagger for our api docs, though to be honest, Socrata's api docs are even easier to use (example). They're open source too. I/O Docs was once a competitor with swagger; not sure if they're still kicking or not.

Anyway, the main takeaway here is providing not just documentation on how to use a geoservices API but generating endpoint-specific documentation / test consoles that theoretically any customer could use (a la how socrata's works with querystrings).