search

gpodder / mygpo

The gpodder.net webservice
http://gpodder.net/
GNU Affero General Public License v3.0
281 stars 87 forks source link

Swagger UI #362

Open SiqingYu opened 4 years ago

SiqingYu commented 4 years ago

Related to https://github.com/gpodder/mygpo/pull/361 and https://github.com/gpodder/mygpo/pull/122

We can host our OpenAPI documentation with a client-consumable YAML/JSON specification file on Swagger.io.

Swagger.io is commercial, and the free plan seems to offer enough features for us. I am trying to contact the SwaggerHub company to see if we can make a better deal, which might be easier for us because we are an open-source project.

To-Dos:

SiqingYu commented 4 years ago

@dellagustin

dellagustin commented 4 years ago

Hello @SiqingYu , I am not familiar enough with the service provided by swagger.io to judge the pros and cons, but I assume it is good for the visibility of the API. Nevertheless I advice to keep the file in source control as I mention here https://github.com/gpodder/mygpo/pull/361#issuecomment-586768480

Best Regards, Guilherme.

SiqingYu commented 4 years ago

@dellagustin Agree. :smile:

cweiske commented 4 years ago

Can't we simply download the latest pre-compiled swagger ui into the static folder, add openapi.yaml in the same directory and make it available that way? There is no need for external hosting since all is static.

(dist folder in the downloads at https://github.com/swagger-api/swagger-ui/releases)

dellagustin commented 4 years ago

@cweiske I don't see any problem with that. Normally I prefer to keep dependencies out of source control, but I can see that mygpo static folder already contains dependencies tracked on the repo, we would be following a pattern that is already in place.