search

mozilla / fxa-oauth-server

OAuth server for Firefox Accounts
48 stars 40 forks source link

Consider using lout to generate API docs #153

Closed seanmonstar closed 8 years ago

seanmonstar commented 9 years ago

The lout can generate a /docs endpoint that automatically documents all other endpoints. It includes the request parameters, all of their validation rules, and the response schemas. By adding a description and tags properties to each route, it will also include the extra information we'd be writing in the API.md file.

The win: docs don't get out of sync. Adding a property, or anything similar, will mean the docs are updated. And each installation will have its own docs, located at /docs (configurable), so people can know what is the state at each stage in our development cycle.

The lose: there's a new endpoint on our servers, run by code that we haven't written nor reviewed. I can assume it's used by Walmart, but still, danger?

@ckarlof @dannycoates considered this for the fxa-auth-server before?

ckarlof commented 9 years ago

I like it in the "each object has a single representation in the system" sense. Not clear if I want it to be running on the production servers, but I have no problem with it running on stable, latest, and nightly.

It might be worthwhile to invest a little time to investigate.

rfk commented 9 years ago

Can it generate a static docs site for reference without a running server? It's not clear from a quick read of the docs.

rfk commented 8 years ago

This has been on the backburner long enough that I'm just going to close it WONTFIX