search

strictdoc-project / strictdoc

Software for technical documentation and requirements management.
https://strictdoc.readthedocs.io/en/stable/
Other
151 stars 24 forks source link

OpenAPI support #1371

Open villanella opened 11 months ago

villanella commented 11 months ago

We need Openapi (Swagger) web view for references to REST API specs.

Popular Openapi publishers like Redoc and Rapidoc support Openapi webview as html injections.

Example:

  1. Add to HTML head the next module import: <script type="text/javascript" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
  2. Provide an ability to inject blocks of HTML/js code into page's body, for example: 
    <rapi-doc-mini
style= "min-width:600px;border: 1px solid #eee; border-top-width:0"
spec-url = "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/json/uber.json"
theme = "light"
paths-expanded = "false"
match-paths = "get /products"
> </rapi-doc-mini>

Syntax of Openapi injection, I think, could be similar to the Mermaid feature syntax:

[FREETEXT]
.. raw:: html

    <rapi-doc-mini
    style= "min-width:600px;border: 1px solid #eee; border-top-width:0"
    spec-url = "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/json/uber.json"
    theme = "light"
    paths-expanded = "false"
    match-paths = "get /products"
    > </rapi-doc-mini>
[/FREETEXT]
stanislaw commented 11 months ago

This one should be easy, and you could do it yourself by following the Mermaid PR: https://github.com/strictdoc-project/strictdoc/pull/1285/files. In that MR, only the documentation is missing, and in this case with OpenAPI, you should probably add the docs, following the Mermaid doc, right away.