Any plans to include UI docs with Exegesis

[Ryan-Gordon]

I have seen other OpenAPI/Swagger frameworks which provide a live documented version of the API usually located at the '/ui' path. I believe this is achieved using swagger-ui.

Would this be possible to include functionality for this with Exegesis as an optional feature? I would be happy to help via PR's
Story:
As a Developer, I want to have the option for generating a UI docs page so that when needed, developers won't have to code it themselves.

[jwalton]

Yeah, I've been putting some thought into that.

Locally right now, I'm hacking this with:

// Import absolute-path directly to get around
// https://github.com/swagger-api/swagger-ui/issues/4502
import pathToSwaggerUi from 'swagger-ui-dist/absolute-path';

...
    const router = new express.Router();

    router.get('/openapi.json', (req, res) =>
        loadOpenapiDoc()
        .then(doc => res.json(doc))
        .catch(err => res.status(500).end(err.message))
    );
    router.get('/openapi.yaml', (req, res) =>
        loadOpenapiDoc()
        .then(doc => res.end(yaml.safeDump(doc)))
        .catch(err => res.status(500).end(err.message))
    );
    router.use('/', express.static(pathToSwaggerUi()));
    router.use(await exegesisExpress.middleware(...));

which exposes the UI at "/" (router here ends up getting mounted in Express at /api/v2, so at the end of the day /api/v2/openapi.yaml gets you the doc, and /api/v2/ gets you docs). This means I need to import the OpenAPI doc myself, though. Also, plugins are allowed to modify the OpenAPI doc, so it would be nice if those modifications were served up via the UI; then I could make exegesis-plugin-roles automatically add a bit to each operation's description listing which roles are required to call the operation, for example, and this would show up in the UI.

So my plan was to make an exegesis-swagger-ui plugin, which would cache a copy of the openapi doc in the preCompile() step, and then serve it and swagger-ui postRouting(). Or something along those lines. :)

[Ryan-Gordon]

Wish I seen this comment a bit earlier before hacking a solution.

I spent some time going through Swagger-UI and different repos/solutions.

I put together a very quick solution that doesn't even use the router.
One route is used to parse the swagger yams file and returns a JSON version of it.
The second route (the one called), gets the JSON data from this first URL and displays.

 app.route('/uidoc')
    .get((req: Request, res: Response) => {
        res.setHeader('content-type', 'application/json');
            res.send(fs.readFileSync(path.resolve(__dirname, './openapi.yaml'),));
        }) 
        
    /**
     * Route responsible for the generation of UI docs
     * 
     * Gets the OpenAPI spec from /uidoc route as a JSON object
     * Takes this JSON object and generates docs using the swagger-ui.ts file.
     */
    app.route('/ui')
    .get((req: Request, res: Response) => {
            //Send the Swagger-UI docs with our OpenAPI spec applied.      
            res.send(swaggerUI.swaggerUI("/ui"));
        }) 

In the code above swaggerUI is a typescript file with a single function returning a HTML string of the swagger docs.
If you decide to move forward with a exegesis-swagger-ui, I can help anytime

[acotty]

The following github repo may help:
https://github.com/phil-mitchell/exegesis-plugin-swagger-ui-express

Update: The plugin worked a treat once I figured out the URL had to end with a / in the browser.