Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Script tag execution and openapi rendering #63

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Script tag execution and openapi rendering #63

wants to merge 1 commit into from

Conversation

vellala2000
Copy link

@vellala2000 vellala2000 commented Apr 20, 2022 •
edited
Loading

closes #61

Supports script tag execution in MD file

Supports Swagger UI for openapi specs loading using html and script tag in MD file as below

<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta
    name="description"
    content="SwaggerIU"
  />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/[email protected]/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
      dom_id: '#swagger-ui',
    });
  };
</script>
</body>
</html>

image

@vellala2000
Copy link
Author

@adrianvlupu Please help review the changes and let me know if we need any adjustments as this is my time engaging in this project.

If all good please help merge these changes when you get a chance. Hope it will help incorporate API specs along with awesome plantuml C4design artifacts.

@MickeJohannesson
Copy link

@vellala2000 Have some questions around this one (I haven't tested it so)

  • Does it work with local openapi.json files? (having a documentation failing because the web api isn't running seems wrong)
  • The Swagger UI present a readonly presentation or are you able to make API calls from it? (Normally I have Swagger activated on my Web API:s in dev/test stage)
  • What happens if you generate a PDF? If it breaks or looks totally weird should it be special case handling for that.

And also a small comment: The option naming should be something like includeSwagger instead of executeScript because it only includes the JS link or not.

@vellala2000
Copy link
Author

vellala2000 commented Apr 21, 2022 •
edited
Loading

@MickeJohannesson

  • Yes its working with local and remote JSON file

  • Try it out feature available and working in swagger UI

  • PDF is generating okay with just one liner showing folder name and path with the example code(see below). it depends on what user decided to do with <html> and <script> tag which are part of markup specifications. However docsify has some limitations on what is supported in . For example in this case I could not import ESM module inside <script>, as per docsify documentation it has to be available in index file otherwise its not able to get the swagger-UI budle .
    image

  • The flag name is actually borrowed from docsify, it enables <script> tags to be executed when specified in markup. Flag actually doing two things: set docsify executescript flag and also adding Swagger-UI library in docsify template. It seems like overkill to add 2 separate flags for each one of them. Let me know what you recommend.

@MickeJohannesson
Copy link

@vellala2000 I think this is a good addon, even though I would like an automatic generated md file with all content instead of the SwaggerUI generation (Need to have the PDF in some cases). Like you add the json-file in the /src directory and in the /docs there would be a generated MD file.

Regarding the naming, sorry but I missed the option in the docsify option. Naming makes more sense then :)

Still will test it out to see how it works, but I haven't got the time at the moment

@vellala2000
Copy link
Author

vellala2000 commented Apr 22, 2022 •
edited
Loading

Yeah I understand where you are coming from.

I looked into widdershins which converts specs into MD file and it looks decent enough for old school :).

to be fair its not easy to make specs readable in documentation.

@vellala2000
Copy link
Author

I am looking forward to use this functionality soon. no pressure :)

this actually completes all types of design documents I am trying to showcase.

@vellala2000
Copy link
Author

I am able to do openapi rendering by using existing custom docsify template option.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Feature: Support openapi static html page generation using swagger UI
2 participants
@vellala2000 @MickeJohannesson