I looking to build a library where some documentation, in one of the standard formats mentioned acts as the router.
For example if I was using API Blueprint and using this documentation.
FORMAT: 1A # My Message [/message] OK, `My Message` probably isn't the best name for our resource but it will do for now. Note the URI `/message` is enclosed in square brackets. ## Retrieve a Message [GET] Now this is informative! No extra explanation needed here. This action clearly retrieves the message. + Response 200 (text/plain) Hello World! ## Update a Message [PUT] `Update a message` - nice and simple naming is the best way to go. + Request (text/plain) All your base are belong to us. + Response 204
A router could simply point to a blueprint file
defmodule MyApp do blueprint "./myapp.api" end
This would then look for modules
MyApp.UpdateAMessage which would be controllers and get routed the correct requests.
I thought this might really put the focus on documentation and be more readable than annotation in existing routing apis, e.g. https://github.com/xerions/phoenix_swagger
My Questions are:
- I think API blueprint looks like the leading contender, what experience do people have and can they share any feedback
- Do any of the above support documenting a streaming endpoint, via server sent events (“text/event-stream”) or perhaps websockets