search

swagger-api / swagger-codegen

swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
http://swagger.io
Apache License 2.0
17.02k stars 6.03k forks source link

[HTML] Theme for API Documentation #5598

Open wing328 opened 7 years ago

wing328 commented 7 years ago
Description

I think it would be a good idea if developers can customize the look and feel of the auto-generated documentation easily by applying different themes. One way is to leverage Google Material Design or Twitter Bootstrap themes as both have a very mature ecosystem (e.g. free, paid themes, web designers who are familiar with these frameworks)

I suggest we start with documentations generated by the html2 generator.

cc @jhitchcock

taxpon commented 7 years ago

@wing328 Do you mean providing an option to specify document template type (Material design, bootstrap, current one and so on)?

wing328 commented 7 years ago

@taxpon yes, ideally developers can choose whether to use material design or bootstrap and then they (or web designers) can customize the look and feel by applying different themes or tweaking the CSS.

To make it easier, we can just start with either material design or bootstrap so as to build up the momentum.

taxpon commented 7 years ago

@wing328 I checked the mustache template in the latest master. Currently, it's already using twitter bootstrap v2.3.2, isn't it ? Regarding twitter bootstrap, do you want to have a new bootstrap template with latest bootstrap (maybe latest stable is v3.3.7)?

Anyway, currently users (developers or web designers) can not inject their own style definitions, I think codegen should provide method to do so (like providing config option). What do you think?

ghost commented 7 years ago

Hey both.

That would be cool. I actually wrote an internal version of these docs at the time that did almost exactly that but it was too tightly coupled to the business at the time to contribute it, And it was a bit thrown together. Originally it was all put in 1 file, as my colleagues at the time wanted to be able to email the html file around to people to open, but that never worked out too well anyway, so separate files might be the way forward.

Another option would be to have a parameter that allows externally referenced stylesheets and javascript as opposed to having it all in one file, and maybe inject a URL for a company logo in the top left

It does currently use bootstrap but I think it could use it 'better' or more standardly, I do like the idea of using a basic MDL layout and styles too, and changing the theme could be really simple, or even having a theme parameter.

The more I think about it the more improvements I think of! I need to find some time to get back into this!

wing328 commented 7 years ago

I checked the mustache template in the latest master. Currently, it's already using twitter bootstrap v2.3.2, isn't it ?

@taxpon likely I'm checking the wrong directory (html?) when writing down this feedback.

Regarding twitter bootstrap, do you want to have a new bootstrap template with latest bootstrap (maybe latest stable is v3.3.7)

It's definitely a good idea to upgrade to v3.3.7 as I know many templates are based on bootstrap v3

I think codegen should provide method to do so (like providing config option).

Config option is one way. Another way I can think of is to pass customized templates via the -t option. Not sure which one the developers prefer and let's see if we hear more feedback from developers on this.

wing328 commented 7 years ago

The more I think about it the more improvements I think of! I need to find some time to get back into this!

@jhitchcock 👍 👍 👍