Set up RapiDoc

[keunes]

Use https://github.com/rapi-doc/RapiDoc to get something pretty like the Podcast Index API specs (code)

[georgkrause]

Whats the advantage of RapiDoc over Swagger in our scenario?

[georgkrause]

@keunes ping :)

[georgkrause]

I will take care for this as soon as the task is clear. Plan is to use Github Actions and Pages.

[keunes]

@georgkrause Pong

Whats the advantage of RapiDoc over Swagger in our scenario?

I have no idea as I'm not familiar with Swagger and only know RapiDoc from the consumption side. Maybe @Sporiff has something to add here?

[Sporiff]

I have no idea as I'm not familiar with Swagger and only know RapiDoc from the consumption side. Maybe @Sporiff has something to add here?

@keunes Swagger UI, RapiDoc, and Redocly will all offer us much the same thing. Rapidoc takes significantly less initial setup since we can just throw an HTML page up and point it at a Yaml file, but none of them are particularly difficult.

The advantage of Swagger UI is we wouldn't be pulling JS from a CDN each time.

[georgkrause]

The advantage of Swagger UI is we wouldn't be pulling JS from a CDN each time.

@Sporiff Thats easy enough to avoid, though. But what is your argument against a CDN?

[Sporiff]

@georgkrause no particular argument, it's just another call. I don't consider it as much of an issue as lack of theming 😛

[keunes]

@Sporiff I guess we could close this one?

I do like the field-level explanations for the responses - we should add the descriptions in our Open API schema file - created #117.

I also think the Podcast Index API specs is a bit easier to process than our API explorer. It looks a bit cleaner thanks to:

• the example & schema being separated by a switch (you don't see both at the same time)
• the different pieces of info (name, type, description) of each field being a bit more compact and one one line/in one row
• the nesting in a response (e.g. the individual subscriptions in our subscriptions endpoint) being expanded by default

Are these things we could configure, or could request support for from the Astro folks?