search

jellyfin / jellyfin-meta

A repository to hold our roadmap, policies, and more.
25 stars 4 forks source link

Provide API browser #4

Closed Shadowghost closed 3 years ago

Shadowghost commented 3 years ago

Since we now have the OpenAPI spec set up, we could provide an api explorer via swagger-ui.

Proposal:

crobibero commented 3 years ago

Can also use https://github.com/Redocly/redoc for a different view :)

nielsvanvelzen commented 3 years ago

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.

Shadowghost commented 3 years ago

I really do not care what API browser we use, anything is fine if we get one 😄

crobibero commented 3 years ago

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

heyhippari commented 3 years ago

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

crobibero commented 3 years ago

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

nielsvanvelzen commented 3 years ago

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?

joshuaboniface commented 3 years ago

Added to https://repo.jellyfin.org/api.html

joshuaboniface commented 3 years ago

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).

joshuaboniface commented 3 years ago

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.