Closed Shadowghost closed 3 years ago
Can also use https://github.com/Redocly/redoc for a different view :)
I personally think redoc has a more friendly UI while displaying the same information. It's also nice if we could use the URL path for the desired API spec. So /10.7.0/
will display that one and /unstable/xxx
will display unstable.
I really do not care what API browser we use, anything is fine if we get one 😄
I just tried the hosted swagger, it didnt like how big our spec was and Firefox attempted to kill the tab a few times before it finally loaded
We should probably use something pre-generated, to reduce the load on browsers.
Hosting it on https://api.jellyfin.org/v10.x/
would be the best, imo
https://github.com/Redocly/redoc/blob/master/cli/README.md
redoc-cli bundle ./jellyfin-openapi-10.7.0~rc1.json --disableGoogleFont
redoc.zip
It's also possible to change the template to provide our own handlebars template and font file
While we're figuring out a way to create a static HTML page, I made this little HTML page that loads the latest stable OpenAPI file and shows it dynamically.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Jellyfin - ReDoc</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<div id="api-doc"></div>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
<script>
const spec = 'https://repo.jellyfin.org/releases/openapi/jellyfin-openapi-stable.json';
Redoc.init(spec, {}, document.getElementById('api-doc'));
</script>
</body>
</html>
Can we upload this to api.jellyfin.org or something similar for now?
Added to https://repo.jellyfin.org/api.html
I actually quite like the idea of this being a dynamic page - saves requiring any additional build steps and such. It's slower to load, but that's a one-time thing (per load, that is).
The version at https://api.jellyfin.org has been implemented.
Version can be specified by adding a version string, or by setting the version
variable, so these two are equivalent and the former will just redirect to the latter.
https://api.jellyfin.org/10.7.0~rc3 https://api.jellyfin.org/?version=10.7.0~rc3
Any valid version (that we have a spec for) is supported. It will automatically look for a stable
version if the version string begins with 10.
, otherwise it will look for unstable specs. With no var set (so the bare URL https://api.jellyfin.org), it will pick the latest stable.
The direct files can be browsed (similar as within the normal repo pages) at https://api.jellyfin.org/openapi/
This script is slow, but I like how flexible it is versus trying to do some static thing with Docker, etc.
Since we now have the OpenAPI spec set up, we could provide an api explorer via swagger-ui.
Proposal: