Upgrade Pender service to provide a UI to its API via OpenAPI

[infojunkie]

Tell us about your request Pender currently uses Swagger 0.x to expose its API on a web page. Upgrade Swagger to use the latest version of OpenAPI (3.x). Evaluate OpenAPI Generator as possible technology.

Tell us about the problem you're trying to solve. What are you trying to do, and why is it hard? Testing and debugging an API during development is much easier when a UI exists to make API calls.

[daniel-shuy]

I'd like to attempt this

[daniel-shuy]

I tried using rswag to generate Swagger YAML/JSON and swagger-ui from rspec-rails specifications.

So far it works well, the only issue is that rswag does not provide a way to convert OpenAPI 3.x JSON/YAML files to Markdown, to replace swagger-docs Swagger JSON to Markdown functionality, which is currently used to generate pender/doc/api.md. Is this an acceptable tradeoff?

[daniel-shuy]

Apparently pender/doc/api.md is no longer in line with the Swagger JSON anyways, so one option is to get rid of the api.md Makefile task but keep the api.md file (since the api.md Makefile task is unusable now anyways).

Alternately, we can use widdershins to convert OpenAPI 3.x JSON/YAML files to Markdown, and update the new OpenAPI definition to match the current api.md. This however requires npm.

Since this will potentially require a lot more effort, I will need a confirmation before continuing to work on this.

So far I've successfully used rswag to generate OpenAPI 3.x YAML/JSON files for the controllers, and displayed them using rswag's embedded swagger-ui. Now I'm migrating the existing controller tests (https://github.com/meedan/pender/tree/v0.113.0/test/controllers) to use rswag (which uses rspec-rails internally).

[danielafeitosa]

Hi @daniel-shuy, Thank you for your interest!

So far I've successfully used rswag to generate OpenAPI 3.x YAML/JSON files for the controllers, and displayed them using rswag's embedded swagger-ui. Now I'm migrating the existing controller tests (https://github.com/meedan/pender/tree/v0.113.0/test/controllers) to use rswag (which uses rspec-rails internally).

Yes, it's an acceptable tradeoff and a great contribution.

Alternately, we can use widdershins to convert OpenAPI 3.x JSON/YAML files to Markdown, and update the new OpenAPI definition to match the current api.md. This however requires npm. Since this will potentially require a lot more effort, I will need a confirmation before continuing to work on this.

You can keep working in this solution, it seems to be a good approach

[daniel-shuy]

@danielafeitosa Thanks for the confirmation! I've created a PR at meedan/pender#233