search

unisonweb / unison

A friendly programming language from the future
https://unison-lang.org
Other
5.81k stars 272 forks source link

codebase server api docs #2614

Open aryairani opened 3 years ago

aryairani commented 3 years ago

Having some docs for the codebase server api would be game-changing for supporting both external and internal tool developers, and as on-boarding for continued maintenance and development of the codebase server.

I see some docs for various types in the form of QueryParam ToParam instances, and some ToSample instances, but I still feel like I'm missing context on how it's all meant to work together.

@runarorama You'd mentioned that docs can be automatically generated with OpenAPI, but how do we actually do that?

I think some prose with examples would go a long way beyond what OpenAPI can give us. I'm not familiar with whether Servant defines some type classes for adding more high-level docs too, but even if it does we'd still need to add and run them :)

aryairani commented 3 years ago

Not sure if relevant: https://swagger.io/resources/articles/documenting-apis-with-swagger/

stew commented 3 years ago

@ceedubs has more experience with swagger than I do

hojberg commented 3 years ago

The markdown we generate has helped me a bit as well, but could use some styling to be more approachable (you find it by going to the root of the api when it's running)

It's a bit more high level than the open api stuff