search

gcentral / Website

The GCentral repository for GCentral.org
MIT License
10 stars 13 forks source link

The GCentral API should be documented in an accessible format to aid contributors and testing. #58

Closed negentropicdev closed 3 years ago

negentropicdev commented 3 years ago

As APIs are designed their interface should be documented using an open standards to help ensure correct implementation, a method of testing before front-ends and API wrappers are developed, and as documentation for developing those front-ends and API wrappers.

I propose adding the Swagger UI to the website which will provide easy to consume documentation for the API within the website itself and generating API specification using the OpenAPI format which can be used in the Swagger UI. Down the road automated tools could be used to embed the annotation for specification generation right within the PHP source.

Additionally each version of the website would provide its applicable version of the API spec. This will allow developers to begin developing against integrated future features of the API on test.gcentral.org as well as allow API developers to simultaneously document and test their new APIs before they're ever integrated into the official develop branch.

For more details check out https://swagger.io/

negentropicdev commented 3 years ago

Integrated swagger UI into website https://test.gcentral.org/swagger and will be in the same location on the live website once released. Also created an API Documentation page for the github wiki.