I have an OpenAPI 3.0 spec and I want to generate a PDF out of it so that it can be given to the end users.
Currently, tools like swagger-spec-to-pdf or swagger2markup only support Swagger 2.0 but not OpenAPI 3.0. Is it possible to generate a PDF from an OpenAPI 3.0 spec without converting it to Swagger 2.0?
A possible solution is to convert your OpenAPI 3.0 definition to an HTML doc, then use a browser's "Save to PDF" feature to convert HTML to PDF.
Follow these steps:
Go to https://editor.swagger.io.
Paste your OpenAPI 3.0 YAML/JSON definition.
Select Generate Client > html.
Download & unzip the file.
Open the index.html page in a browser, e.g. Chrome.
Select File > Print, change the Destination to Save as PDF, and save the page.
I just found RapiPDF which is able to generate PDF from OpenAPI 3.0 definition.
But it still isn't an ideal tool I'm looking for. I found these limitations so far:
No CLI, runs only in browser. So I can't use it in an automate pipeline.
Callback is not supported
No example in generated document
You can use this site and post your OpenAPI 3.0 spec (in json) directly into it. It's the easiest way, I think and the generated PDF looks pretty.
The following 2 packages helped me generate a PDF from OpenAPI json file:
org.openapitools:openapi-generator-gradle-plugin:5.0.0-beta2
org.asciidoctor:asciidoctor-gradle-jvm-pdf:3.2.0
Apply the relevant Plugin classes and the rest is pretty straight-forward task configuration. This is my groovy plugin but it shouldn't be difficult to find the corresponding gradle DSL extensions should you need to.
project.plugins.apply OpenApiGeneratorPlugin
GenerateTask adoc = project.tasks.withType(GenerateTask).iterator().next()
adoc.with {
it.input = swagger.outputDir.path + '/' + swagger.outputFileName + '.json'
it.generatorName.set 'asciidoc'
it.outputDir.set swagger.outputDir.path
// Leaving the below option empty can cause rendering issues
it.configOptions.putAll([
'infoUrl' : 'https://example.com',
'infoEmail': 'inbox#example.com',
])
}
project.plugins.apply AsciidoctorJPdfPlugin
project.tasks.withType(AsciidoctorPdfTask).iterator().next().with {
it.sourceDir = adoc.outputDir
it.outputDir = it.sourceDir
}
Let me know if there are questions about (or syntax errors in) this snippet.
DocBaker for OpenAPI: https://curvednebula.com/docbaker/
I'm the developer of the tool.
The easiest and nicest solution I found it is just using the usual https://editor.swagger.io/. Once you are happy with the generated outcome (on the right), just drag the central cursor on the left (to cover your source code) in order to visualise only the final documentation. Then if you use Chrome (similarly for Firefox), just (right button in the screen or from menu) choose "Print" and for "Destination" select "Save As PDF".
Related
I have to change the path of the swagger json file, in nestjs documentation it is http://localhost:3000/api-json but for the standard have to keep it
http://localhost:3000/api/openapi.json
Let me know if there is any possible solution for it.
since v6.2 of #nestjs/swagger you can change that value using the jsonDocumentUrl/yamlDocumentUrl option like so:
SwaggerModule.setup('api', app, document, {
jsonDocumentUrl: 'openapi.json'
});
I try to make my gatsby page multilingual.
I am using gatsby-plugin-react-i18next, i18next and react-i18next like in documentation.
i18n adds language prefix but page url is still the same. How i can translate friendly url?
i have: domain/es/hello-world
but i want: domain/es/hola-mundo
Is there a simple solution to this in GatsbyJS or is it more complicated?
I have found a solution to our problem. I have created a .json file with the original path and the one I want to change. For example: /es/contact/": "/es/contacto.
I create this file manually, and I add a path for each page that I want to change the path. Then, in the gataby-node file, I create the oncreatepage api (there is documentation for this api). In this function, I take the page parameter.
if page.path == to some .json file path, change the path to that of the .json file.
Thks for help. Finally i found perfect answer for my needs. gatsby-plugin-i18n-l10n have all i need for multilingual gatsby website with url translation too. I really recommend this module and I appreciate the work of the creators.
Here is link to github where you can find that plugin:
gatsby-plugin-i18n-l10n
Is there any way to visualize swagger YAML file inside ReadeMe.md. Only way I can put file
[Swagger Codegen](/assets/swagger.yaml)
my structure for codebase is
Project
src
assets
swagger.yaml
ReadeMe.md
You can try convert the swagger.yaml to markdown, then put it in readme.
Conversion tools like: https://github.com/syroegkin/swagger-markdown
There's a online demo here: https://swagger-markdown-ui.netlify.app/
Hiho,
I use the ckeditor on my website for special textareas like forum
or signatures.
But I have a problem with the output. I use ZF2 and would like to
use ZendMarkup to render the output bbcode back in html.
But at every time I call
$bbcode->render(...)
I got the error
There is no Zend_Markup_Root markup.
The ZendMarkup is an extension inspired by the Zend_Markup from ZF1.
But I can't find any thing on API or other guides.
Does someone has any idea what as the problem is?
The ZendMarkup library is very old (last update is 10 months ago!) so I wouldn't use such library. If you would like, I think I traced the error down.
On this line there is a reference to Zend_Markup_Root while that should be ZendMarkup\Renderer\Markup\Html\Root. Try to change that line and see what happens.
Another way is to replace the ZendMarkup library with another library which does work and is updated regularly. An example is Decoda. If you load mjohnson/decoda in your composer.json, you can use Decoda in your Zend Framework 2 application:
<?php
use Decoda\Decoda;
$parser = new Decoda($bbcode);
$html = $parser->parse();
With tools like composer, there is no need to use solely Zend* components when there are better alternatives.
Something that I've had a good hard look for and I have not been able to find, is how to efficiently obtain a hard copy of Javadocs? Obviously, one solution is simply to navigate to each page and execute a browser print, but there's got to be a better way! Do you guys have any ideas?
You can use DocBook Doclet (dbdoclet) to create DocBook XML from your JavaDoc Comments. The DocBook XML can then be transformed to PDF or (Singlepage-)HTML.
You can call the tool from the commandline. Point it to your class files and it will generate the DocBook XML. This works similar to the javadoc command which will generate the JavaDoc HTML. Example:
./dbdoclet -sourcepath ~/my-java-program/src/main/java -subpackages org.example
The result is a DocBook XML file in a dbdoclet subdirectory which can be used to create a PDF or HTML file. This can also be done from the command line; I am using the docbkx-maven-plugin for this.
You can do mass conversions with it, but it would require some time to make it work the way you want.