Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve exportOpenApi task for easier integration into master documents #1179

Open
mh182 opened this issue May 19, 2023 · 0 comments · May be fixed by #1178
Open

Improve exportOpenApi task for easier integration into master documents #1179

mh182 opened this issue May 19, 2023 · 0 comments · May be fixed by #1178
Assignees

Comments

@mh182
Copy link
Collaborator

mh182 commented May 19, 2023

Make the task exportOpenApi more flexible so the OpenAPI specification in Ascidoc format can be integrated into existing documentation in Asciidoc format (for example into the arc42 template).

The proposed changes are based the comment on how to integrate OpenApi specification into ar42 documentation

Describe the solution you'd like

  • The OpenAPI specification file can be provided via command line with -P openApi.specFile=some-path/to/the-spec.yaml
  • The location/name of the generated Asciidoc format of the OpenAPI specification can be configured. This should be optional. If not provided, create the file in ${targetDir}/OpenAPI.
  • Instead of providing infoEmail and infoUrl the user can configure additionalProperties. This way the export provides more flexibility.
  • Provide output on console where the Asciidoc file was created.

The proposed change to the configuration for the exportOpenApi would look something like

openApi = [:]

openApi.with {
    specFile = 'src/docs/petstore-v2.0.yaml'

    // outputDir = "${targetDir}/OpenAPI"        // optional

    //additionalProperties = [                                 // optional
    //    infoUrl = 'https://my-api.example.org'
    //    infoEmail = '[email protected]'
    //    headerAttributes = false
    //]
}

Describe alternatives you've considered
None. But I would be glad if someone would come up with something else.

Additional context
This issue will not address #1167 but we should discuss how we could configure the export of more than one OpenAPI specification.

@mh182 mh182 self-assigned this May 19, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant