search

irods / irods_client_http_api

An iRODS C++ HTTP API using Boost.Beast
BSD 3-Clause "New" or "Revised" License
0 stars 6 forks source link

Investigate API documentation tools #61

Open korydraughn opened 11 months ago

korydraughn commented 11 months ago

There are a number of tools available for documenting HTTP-based APIs. We should consider using one.

Known Tools:

Are there others?

trel commented 11 months ago

The OpenAPI Spec, is formerly known as the Swagger Spec.

trel commented 11 months ago

https://github.com/Redocly/create-openapi-repo

trel commented 11 months ago

https://www.openapis.org/

korydraughn commented 8 months ago

I've spent some time investigating OpenAPI and at this time, it feels very complicated and cumbersome to use.

Until the tools become better, we're going to stay away from maintaining an OpenAPI file. For now, a markdown file is perfectly fine.

Aside from that, JSight looks like a promising alternative. It seems simple. We'll need to investigate whether it can do what we want before committing to it.