I have created a Swagger documentation with a yaml file under:
api/swagger/swagger.yaml
Now I want to share a static HTML document with its definition, yet it was stated on the swagger project, that they don't plan to support HTML generation at all.
How can I generate a static HTML file from a Swagger project?
On
The easiest way I can think of is to use Swagger Editor:
editor.swagger.io uses generator.swagger.io to generate API clients, server stubs and documentation, and generator.swagger.io is powered by the open-source project Swagger Codegen.
On
./swagger.json (or whatever your swagger json is called) (see here)
On
Are you trying to export it to create single documentation from different services? If yes, an alternative might be https://github.com/varghgeorge/microservices-single-swagger. This simple springboot microservice will show all your swagger documentation (from different servers) in one place based on YAML config.
On
Another answer suggested the Swagger Editor
, which is great. However, to obtain a single file to import into it:
npm install -g @apidevtools/swagger-cliswagger-cli bundle openapi.yaml --outfile ./openapi-expanded.json --type jsonThe above command assumes your root file is named openapi.yaml and you want an output JSON file openapi-expanded.json: that JSON is what you'll import.
On
Use an HTML file like this to load your OpenAPI definition:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css">
<title>Your App API v1</title>
<body>
<div id="your-app-docs" />
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
window.onload = function () {
const ui = SwaggerUIBundle({
url: "openapi.yml",
dom_id: "#your-app-docs",
deepLinking: true,
})
}
</script>
</body>
</html>
You can then later host it locally or use a service like Netlify to host it on the web.
There is swagger2markup-cli that can generate a static
adocfile.Ensure that you have Java runtime installed. (I am using
Java(TM) SE Runtime Environment (build 1.8.0_111-b14)).You fetch the jar:
And you can generate the a static
adocwith it via:That adoc file can then be converted into a
htmlfile viaasciidoctor:You may need to install it, as I am using Ubuntu, I could via: