Generate PDF from Swagger API documentation

Question

I have used the Swagger UI to display my REST webservices and hosted it on a server.

However this service of Swagger can only be accessed on a particular server. If

Answer 1

You can modify your REST project, so as to produce the needed static documents (html, pdf etc) upon building the project.

If you have a Java Maven project you can use the pom snippet below. It uses a series of plugins to generate a pdf and an html documentation (of the project's REST resources).

1. rest-api -> swagger.json : swagger-maven-plugin
2. swagger.json -> Asciidoc : swagger2markup-maven-plugin
3. Asciidoc -> PDF : asciidoctor-maven-plugin

Please be aware that the order of execution matters, since the output of one plugin, becomes the input to the next:

    com.github.kongchen
    swagger-maven-plugin
    3.1.3
    
        
            
                false
                some.package
                /api
                
                    
                    Add some description
                    v1
                
                ${project.build.directory}/api
                true
            
        
    
    
        
            ${phase.generate-documentation}
            
            
                generate
            
        
    


    io.github.robwin
    swagger2markup-maven-plugin
    0.9.3
    
        ${project.build.directory}/api
        ${generated.asciidoc.directory}
        
        asciidoc
    
    
        
            ${phase.generate-documentation}
            
                process-swagger
            
        
    


    org.asciidoctor
    asciidoctor-maven-plugin
    1.5.3
    
        
            org.asciidoctor
            asciidoctorj-pdf
            1.5.0-alpha.11
        
        
            org.jruby
            jruby-complete
            1.7.21
        
    
    
        ${asciidoctor.input.directory}
        
        swagger.adoc
        
            book
            left
            2
            ${generated.asciidoc.directory}
            
        
    
    
        
            asciidoc-to-html
            ${phase.generate-documentation}
            
                process-asciidoc
            
            
                html5
                ${generated.html.directory}
                
            
        
        
            asciidoc-to-pdf
            ${phase.generate-documentation}
            
                process-asciidoc
            
            
                pdf
                ${generated.pdf.directory}
                
            
        
    

The asciidoctor plugin assumes the existence of an .adoc file to work on. You can create one that simply collects the ones that were created by the swagger2markup plugin:

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]

If you want your generated html document to become part of your war file you have to make sure that it is present on the top level - static files in the WEB-INF folder will not be served. You can do this in the maven-war-plugin:

    maven-war-plugin
    
        WebContent
        false
        
            
                ${generated.html.directory}
            
            
            
                ${generated.pdf.directory}
            
            
        
    

The war plugin works on the generated documentation - as such, you must make sure that those plugins have been executed in an earlier phase.