search

ome / design

OME Design proposals
http://ome.github.io/design/
1 stars 15 forks source link

Documentation for web api #68

Open atarkowska opened 7 years ago

atarkowska commented 7 years ago

Following the web api discussions and design https://github.com/openmicroscopy/design/pull/43 looks like handwriting documentation in o.org website may not be sufficient and even misleading for users. OMERO.web is a framework so API documentation should follow the same pattern. Hosting web api doc along side the client under the same url brings advantages for users and developers, especially for custom applications. There are various frameworks http://www.django-rest-framework.org/topics/documenting-your-api/ adopted for Django REST api, so that shouldn't be a big issue to follow the same pattern.

I tried already Swagger, and looks promising. Most I liked was that you can make direct request from the doc. This could be also useful for testing.

cc @will-moore @chris-allan @joshmoore @manics @jburel @emilroz

manics commented 6 years ago

From what I've seen in other APIs Swagger looks quite nice, and follows the OpenAPI Specification.