Using Material for MkDocs and PyMdownX for some REST API Doc design

[Andre601]

The goal was to make API documentation that MIMICS OpenAPI in terms of design. With that said is the shown content NOT the result of using OpenAPI. This is all hand made using the details and snippets expansion from PyMdownX.

General look:

POST content:

Success Response:

Failed Responses:

---

GET content:

Success Response:

Failed Responses:

[squidfunk]

Very cool! I've seen some attempts to generate documentation from OpenAPI specs – really awesome to see some innovation in that space, and this already looks pretty good.

[Andre601]

Well... thing is that this isn't generated from OpenAPI secs. It's hand made.

[martinbira]

Ah :( I was excited because our implementation, https://docs.apptus.com/esales-4/integration/api/specification/ , is generated from our OpenAPI spec, but since we use Swagger UI, it looks like meh.

[jromal]

I used this for a test and it looks nice.
https://github.com/bharel/mkdocs-render-swagger-plugin

It connects online so it renders (almost) identical as on the swagger.io (some colors are not the same).

[Andre601]

What does the output look like?
I saw that plugin too, but the fact that there isn't even an example of how it would look like makes me not that interested in spending time to work with it...

[jromal]

It looks like the same as on the web. Actually it connects to the swagger.io or you need to download the swagger-ui.js file (like I do).

The only difference is that the combination of colors make it unreadable in some cases (e.g. examples with light option or some texts with dark option).

While the same at swagger.io looks much better because background is black. I guess, but could be totally wrong, that some of the settings of the material mkdocs overwrite the color of this background. But no idea at all.

[jromal]

A colleague of mine is using with a local server and using standard template colors. The background of examples is light grey and makes green not readable, and the dark mode makes all black text unreadable.

Definitively there is a conflict between this plug-in and swagger-ui.js with Material for Mkdocs. Maybe some specific background colors can be forced for that javascript part. In any case it is not my biggest priority and will wait if/when someone finds a way to make it nicer.

Thanks.

[blueswen]

Hi @javier-romera. If you are still looking for a dark mode of Swagger UI compatible with Material for MkDocs, you can consider my mkdocs plugin mkdocs-swagger-ui-tag. The effect as follow:

[jromal]

Great.

It solves my problem of lack of contrast in the examples that I had with the previous plugin.
Very nice job.

Many thanks.

[Andre601]

You should reply within the answer and not in a separate answer... Makes it feel disconnected.

[Andre601]

The latest admonition changes look really nice for my API Docs (Again, no swagger, only manual design)

[squidfunk]

Nice! That looks indeed very slick 💅

[Andre601]

Still wish there was some plugin for MkDocs that would utilize <details> like this to generate the docs based on an OpenAPI Spec.
The ones suggested here are... meh. Mostly not really fitting that well into the style of material.

(Although, now details look more like the stuff swagger is using)

[Andre601]

Funny enough is the actual docs not updated yet... Guess it's caching doing its thing here, so I'll have to wait for that to update.

[squidfunk]

Are you referring to our documentation? It is, in fact, using the latest admonition design.

[Andre601]

No. My own docs

[Andre601]

Decided to try and switch over to OpenAPI spec using the swagger-ui-tag plugin mentioned in these discussions.

Changed some CSS a bit to make colours match the general MkDocs material theme a bit closer.

[Hela-Masri-shift]

how such a plugin can work if we use a github action to publish the website to a github pages?

[Andre601]

It just works?
All you need is a yaml/json file of your openapi spec and the proper dependencies installed.

As of right now am I using my own hook for the api generation together with essentials-oapi to parse a json file.

[Andre601]

Just for the sake of being up-to-date and giving proper info is here my current setup:

I use a hook (Single python file MkDocs can load to execute stuff almost like a plugin) to look for a specific text in a page and when found use Essentials OpenAPI to create a new Jinja2 parser with modified templates to generate the output.

It's effectively the mkdocsoad plugin, but modified to fit my own design need (And to reduce depenencies).

The hook: https://github.com/purrbot-site/Docs/blob/master/theme/.hooks/api_docs_gen.py
The jinja2 files: https://github.com/purrbot-site/Docs/tree/master/theme/.hooks/theme/views_mkdocs

The result: