9
votes

Comment générer un PDF ou un balisage à partir d'OpenAPI 3.0?

J'ai une spécification OpenAPI 3.0 et je souhaite en générer un PDF afin qu'il puisse être donné aux utilisateurs finaux.

Actuellement, des outils tels que swagger-spec-to-pdf ou swagger2markup prend uniquement en charge Swagger 2.0 mais pas OpenAPI 3.0. Est-il possible de générer un PDF à partir d'une spécification OpenAPI 3.0 sans le convertir en Swagger 2.0?

swagger openapi

0 commentaires

4 Réponses :

15
votes

Une solution possible consiste à convertir votre définition OpenAPI 3.0 en document HTML, puis à utiliser la fonction "Enregistrer au format PDF" d'un navigateur pour convertir le HTML en PDF.

Suivez ces étapes:

Accédez à https://editor.swagger.io .
Collez votre définition YAML / JSON OpenAPI 3.0.
Sélectionnez Générer le client> html .
Téléchargez et décompressez le fichier.
Ouvrez la page index.html dans un navigateur, par exemple Chrome.
Sélectionnez Fichier> Imprimer , remplacez la Destination par Enregistrer au format PDF et enregistrez la page.

1 commentaires

Pour info, il y a le 'openapi-generator-gradle-plugin' qui rend les étapes 1 à 4 y compris redondantes.

3
votes

Je viens de trouver RapiPDF qui est capable de générer un PDF à partir de la définition OpenAPI 3.0.

Mais ce n'est toujours pas l'outil idéal que je recherche. J'ai trouvé ces limitations jusqu'à présent:

Pas de CLI, ne fonctionne que dans le navigateur. Je ne peux donc pas l'utiliser dans un pipeline automatisé.
Le rappel n'est pas pris en charge
Aucun exemple dans le document généré

0 commentaires

0
votes

Les 2 packages suivants m'ont aidé à générer un PDF à partir d'un fichier json OpenAPI:

org.openapitools: openapi-generator-gradle-plugin: 5.0.0-beta2
org.asciidoctor: asciidoctor-gradle-jvm-pdf: 3.2.0

Appliquez les classes Plugin appropriées et le reste est une configuration de tâches assez simple. C'est mon plugin génial mais il ne devrait pas être difficile de trouver les extensions DSL gradle correspondantes si vous en avez besoin.

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
}

Faites-moi savoir s'il y a des questions sur (ou sur la syntaxe erreurs dans) cet extrait.

0 commentaires

0
votes

Vous pouvez utiliser ce site et y publier directement vos spécifications OpenAPI 3.0 (en json). C'est le moyen le plus simple, je pense et le PDF généré est joli.

0 commentaires