Integrating OpenAPI specification into arc42 documentation

[mh182]

I have a hard time to understand how the different docToolchain tasks work together, so that I can create a more complex document.

My goal: I would like to integrate the OpenAPI specification into my architecture document (started from an arc42 template).

The structure in my repository looks like the following:

src/
└── docs
    ├── arc42
    │   ├── arc42.adoc
    │   └── chapters
    │       ├── 01_introduction_and_goals.adoc
    │       ├── 02_architecture_constraints.adoc
    │       ├── 03_system_scope_and_context.adoc
    │       ├── 04_solution_strategy.adoc
    │       ├── 05_building_block_view.adoc
    │       ├── 06_runtime_view.adoc
    │       ├── 07_deployment_view.adoc
    │       ├── 08_concepts.adoc
    │       ├── 09_architecture_decisions.adoc
    │       ├── 10_quality_requirements.adoc
    │       ├── 11_technical_risks.adoc
    │       ├── 12_glossary.adoc
    │       ├── about-arc42.adoc
    │       └── config.adoc
    ├── images
    │   ├── 01_2_iso-25010-topics-EN.drawio.png
    │   ├── 05_building_blocks-EN.png
    │   ├── 08-Crosscutting-Concepts-Structure-EN.png
    │   └── arc42-logo.png
    └── petstore-v3.0.yaml

Adding openApi.specFile=src/docs/pestore-v3.0.yaml and calling exportOpenApi generates the Asciidoc file in build directory:

build
└── OpenAPI
    └── index.adoc

How could I integrate the newly generated build/OpenAPI/index.adoc into one of the chapters of my architecture document?

Let's assume the OpenAPI specification should be included in 05_building_block_view.adoc as part of the interface description of a "Black Box".

I have the following questions:

1. How do you include the generated Asciidoc file?
   I see two options:
   • Include the file with a relative path to build: this shows me explicitly that the file was generated, but it seems awkward.

   === Whitebox Overall System
   ...
   
   ==== Pet Store
   
   This is just an example how to integrate the OpenAPI specification of the pet store.
   
   include::../../../../build/OpenAPI/index.adoc[]
   
   _<(Optional) Quality/Performance Characteristics>_
   
   _<(Optional) Fulfilled Requirements>_
   
   _<(Optional) Open Issues/Problems/Risks>_
   
   ==== <Name black box 2>
   
   _<black box template>_
   ...
   

   • Copy the generated file into src/docs/arc42/chapters manually after exporting it: this is tedious (and error-prone) during the process of writing the OpenAPI spec.
2. How do you handle the meta-data (:toc:, :numbered:, ...) of index.adoc which screws up the document?
3. How do you handle the heading structure of generated Asciidoc file? They do not fit into the context of the chapter.

[obfischer]

Hi @mh182,

some days ago I had the same problem to solve. I create the OpenAPI documentation with a custom task, which is based on the exportOpenApi task, but with the additional property headerAttributes:false. This property suppresses the generation of header attributes for the resulting AsciiDoc document.

Then I included the resulting AsciiDoc document in my documenation via in include directive.

include::../../../../target/api-specification/index.adoc[]

The whole process of the generation of the documenation is orchestered by an shell script, similar to this excerpt:

declare apiSpecs=(
'../api-specifications/src/main/openapi/b-api.yaml'
'../api-specifications/src/main/openapi/a-api.yaml'
)

for apiSpec in ${apiSpecs[@]}; do
  doctoolchain . myExportOpenAPITask -DapiSpec=${apiSpec}

  # Extrahieren des Namens für die API. Diesen brauchen wir, um die generierte API-Dokumentation
  # an die richtige Stelle zu verschieben nach der Generierung
  apiName=$(echo ${apiSpec} | cut -d '/' -f 3)

  rm -r -f target/${apiName}
  mv -v target/OpenAPI target/${apiName}
done

And finally here is my custom task to generate the OpenAPI documentation without the meta-data/header attributes:

buildscript {
    repositories {
        maven {
            credentials {
                username mavenUsername
                password mavenPassword
            }
            url mavenRepository
        }
    }
    dependencies {
        classpath "org.openapitools:openapi-generator-gradle-plugin:6.5.0"
    }
}
apply plugin: 'org.openapi.generator'

def specFile = config.openApi.specFile

task myExportOpenAPITask(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask, group: 'docToolchain', description: 'exports OpenAPI specification to the asciidoc file') {

    if (!specFile) {
        logger.info("\n---> OpenAPI specification file not found in Config.groovy (https://doctoolchain.github.io/docToolchain/#_exportopenapi)")
        return
    } else {
        logger.info("Found OpenAPI specification in Config.groovy")
    }

    outputs.upToDateWhen { false }
    outputs.cacheIf { false }
    generatorName = 'asciidoc'
    outputDir = "${targetDir}/OpenAPI".toString()
    inputSpec = "${docDir}/${specFile}" // plugin is not able to find file if inputPath is defined as '.'

    logger.debug("\n=====================\nProject Config:\n=====================")
    logger.debug("Docdir: ${docDir}")
    logger.debug("Target: ${targetDir}")
    logger.info("\n=====================\nOpenAPI Config:\n=====================")
    logger.info("Specification file: ${specFile}")
    logger.info("inputSpec: ${inputSpec}")
    logger.info("outputDir: ${outputDir}\n")

    additionalProperties = [
            infoEmail:"${config.openApi.infoEmail}",
            infoUrl:"${config.openApi.infoUrl}",
            headerAttributes:false
    ]
}

[mh182]

Thanks a lot for your feedback.

Based on your solution, I can gather the following areas in which the current task lacks on flexibility:

• provide openApi.specFile via command line
• provide means to define the output directory
• user defined additionalProperties which we can be passed to the org.openapitools.generator.gradle.plugin.tasks.GenerateTask
• support for multiple OpenAPI specifications (this was already requested with Support for multiple OpenAPI specifications #1167)