nice and friendly markdown version of the REST API

[jbibla]

we need a document outlining how to use the REST API and it's relationship to the LCD. maybe this is one document, maybe it's two. whatever ya'll think is best.

- Markdown version of the REST API
- Documentation on how to start/configure the Rest server

@gamarin2 said he is up for the task 🎉
@faboweb for your information ℹ️

[jbibla]

@gamarin2 any progress?

[faboweb]

To keep up to date with the API a document that is decoupled from code apparently is hard to maintain. The current Swagger document is only ever updated by me. I talked to the SDK team and we want to further spike automatic documentation in Swagger format. I hope that there is first outcomes this week.

[gamarin2]

No progress for now. @faboweb why keep swagger instead of markdown? It would be nice to integrate the doc with VuePress

[faboweb]

To keep up to date with the API a document that is decoupled from code apparently is hard to maintain. The current Swagger document is only ever updated by me.

[faboweb]

Adding: If you know of a good tool that solves this problem I am not opposed to markdown/VuePress at all.

[jbibla]

there is an important difference between general documentation (explanations of what the code does and what you need to know about it - in english for now) and documenting the API. we'll need both and both will be in markdown for sure - but having swagger or slate as well is an option for more interactive API docs. eventually, we can build a vue component for interactive API docs so it can live in vuepress with everything else.

@gamarin2 if you're up for it - we could really use a doc about what the LCD is, why it's important, and how it relates to the REST API. but if not you now, maybe you can think of someone who can pick it up?

looping in @ebuchman as potential assigner of this task.

[faboweb]

👍 for documenting what the LCD is and how to use it.

[gamarin2]

There is already an effort for a MVP doc of REST server: #1139

[adrianbrink]

This is being tackled in #1314 . Any help would be appreciated. Please create PRs against the main PR.

[faboweb]

I want to note again that a static documentation might be the wrong way to go as people tend to not update the documentation on API changes. This was brought up by @zramsay . And from experience working with the LCD I tend to agree.

[adrianbrink]

What's the best way to autogenerate documentation from the LCD?

[faboweb]

I tried https://github.com/smacker/go-swagger-gen

[jbibla]

i believe some folks have also used https://github.com/lord/slate

[faboweb]

Upside of swagger is, that there are tools to automatically test the created API vs the spec which could reduce bad documentation and therefor developer frustration. Example here: https://github.com/earldouglas/swagger-test
Another advantage of swagger is the ability to create mock servers directly from the spec: https://github.com/subeeshcbabu/swagmock
This could help developers with testing and integration.

I don't now if we need any of this now though.

[jackzampolin]

This is in process with the Bianje work.

[jackzampolin]

Going to close this issue as complete.