Menu
For some REST APIs written in PHP, I was asked to create Swagger documentation, and since I was not aware of any easy way of adding annotations to those existing APIs and create such a documentation, I used this editor to generate some for now.
I saved the JSON and YAML files created using that editor, and now I need to create the final interactive Swagger documentation (this statement might sound naive and vague).
Can someone please let me know how I can convert the Swagger JSON specification file to actual Swagger documentation?
I am on the Windows platform and do not know anything about Ant/Maven.
724
The easiest way I can think of is to use Swagger Editor: Go to: https://editor.swagger.io. Click on "File" in the top menu bar and then select "Import File" After import, click on "Generate Client" in the top menu bar, and then select "HTML" or "HTML2" to generate static HTML documentation.
Their is no such tool or functionality to export swagger documentation into PDF or any other doc. You need to convert your swagger. json file to yaml file then u can get swagger as html doc form http://editor.swagger.io/.
If you don't see the url or if url is a code expression, open the browser dev tools, switch to the Network tab and disable caching. Then refresh the page and search for the API definition file ( swagger. json , swagger. yaml , api-docs or similar) among HTTP requests.
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. The major Swagger tools include: Swagger Editor – browser-based editor where you can write OpenAPI specs. Swagger UI – renders OpenAPI specs as interactive API documentation.
Try to use redoc-cli.
I was using bootprint-openapi by which I was generating a bunch of files (bundle.js, bundle.js.map, index.html, main.css and main.css.map) and then you can convert it into a single .html file using html-inline to generate a simple index.html file.
Then I found redoc-cli very easy to to use and output is really-2 awesome, a single and beautiful index.html file.
Installation:
npm install -g redoc-cli
Usage:
redoc-cli bundle -o index.html swagger.json
I was not satisfied with swagger-codegen when I was looking for a tool to do this, so I wrote my own. Have a look at bootprint-swagger
The main goal compared to swagger-codegen is to provide an easy setup (though you'll need nodejs).
And it should be easy to adapt styling and templates to your own needs, which is a core functionality of the bootprint-project
32
Everything was too difficult or badly documented so I solved this with a simple script swagger-yaml-to-html.py, which works like this
python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html
This is for YAML but modifying it to work with JSON is also trivial.
32
I spent a lot of time and tried a lot of different solutions - in the end I did it this way :
<html>
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css">
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
function render() {
var ui = SwaggerUIBundle({
url: `path/to/my/swagger.yaml`,
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
});
}
</script>
</head>
<body onload="render()">
<div id="swagger-ui"></div>
</body>
</html>
You just need to have path/to/my/swagger.yaml served from the same location.
(or use CORS headers)
23
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
