add theme option

[Uzlopak]

Closes #13 Closes #35 Closes #38

First we should discuss if the approach is OK or not. So basically I introduce a theme option. The theme option can handle additional javascript, additional css files and additional favicons. See the corresponding typescript interface. I guess we need also to calculate the CSP of the files on plugin load, which is not yet implemented but should be a no-brainer.

So lets discuss if it is the right approach.

So for the request of @OkanPinar in #35 you would do:

'use strict'

const fastify = require('fastify')({ logger: true })
const { SwaggerTheme } = require('swagger-themes');

fastify.register(require('@fastify/swagger'), {
  mode: 'static',
  specification: {
    path: './examples/example-static-specification.json'
  }
})
fastify.register(require('../index'), {
  theme: {
    css: [
      { filename: 'theme.css', content: new SwaggerTheme('v3').getBuffer('dark') }
    ],
  }
})

fastify.listen({ port: 3000 }, (err) => {
  if (err) throw err
})

Taking the example of @Xpucmoc-Bockpec for #13

'use strict'

const fastify = require('fastify')({ logger: true })
const css = `h2 + a, section .models, .download-url-wrapper {
  display: none!important;
}

.topbar {
  background-color: #002f6c!important;
}

.opblock-get .opblock-summary-method {
  background-color: #0048a6!important;
}

.topbar-wrapper {
  height: 45px;
  background-repeat: no-repeat;
  background-size: contain;
  background-image: url("hello.svg");
}

.topbar-wrapper img {
  display: none;
}`

fastify.register(require('@fastify/swagger'), {
  mode: 'static',
  specification: {
    path: './examples/example-static-specification.json'
  }
})
fastify.register(require('../index'), {
  theme: {
    css: [
      { filename: 'theme.css', content: css }
    ],
  }
})

fastify.listen({ port: 3000 }, (err) => {
  if (err) throw err
})

Checklist

• [ ] run npm run test and npm run benchmark
• [ ] tests and/or benchmarks are included
• [ ] documentation is changed or added
• [ ] commit message and code follows the Developer's Certification of Origin and the Code of conduct

[mcollina]

Can you include one or two examples of what can be achieved with this themes?

Can the logo at the top left be replaced?

[Uzlopak]

The Logo is an image and that image is the 64x64 favicon. So the answer is yes, but on the other hand also kind of not that "clever" as it is not possible to completely theme the swagger documentation.

Maybe it makes more sense to have a theme option which basically mounts a folder with fastify-static to /static/theme. And we basically expect that the theme folder contains a index.css with the overriding css or maybe index.html overriding everything. Benefit of that would be, that an implementer could put all files into the theme-folder, reducing the configuration overhead and be in full controle of the output.

[mcollina]

I think that would be better.

[Uzlopak]

Mounting the theme folder seems to be elegant, but then it is not easy to just hook those swagger-themes.

[mcollina]

Let's land this and see. Tests are failihg

[Uzlopak]

I will probably implement it tomorrow

[ilyamixaltik]

As support for the swagger-themes library will be added, please write. I will update the library documentation.

[ilyamixaltik]

Are there any successes?