Skip to content

Add OpenAPI definitions and Swagger UI

embr requested to merge feature/ratdash-apidocs into develop

Issue Fix

Fixes #54 (closed), blocker for #56 (closed)

Description

This adds an endpoint that returns an OpenAPI (formerly Swagger) definition blob for the API - currently with a whopping one endpoint.

OpenAPI is a somewhat overengineered, but very useful spec for making "self-describing" APIs, with quite a few bits of tooling written around it - including code generators for client libraries in a variety of languages, if that's your thing.

Most notably, however, it has Swagger UI - a combined documentation viewer and interactive console, which lets you play around with an API in your browser. I've added this to the dashboard under /api.

Alternative(s) considered

The main goal here is to document the API in a useful way, and the OpenAPI + Swagger UI combo is a surprisingly decent counterpart to rustdoc. The interactive console and code generation potential is side effect, albeit a very useful one.

If this feels too overkill, I'm sure I could find some alternative approach. There's also several different frontends that all consume the same OpenAPI spec, eg. Redoc.

Type

Choose one: Feature

Screenshots (if applicable)

Overview: image

Expanding an endpoint and a type definition: image

"Try it out": image

"Execute": image

Edited by embr

Merge request reports