[BUG] [asciidoc] Unresolvable include path by asciidoctor processor
Created by: LEZIER-S2
Bug Report Checklist
-
Have you provided a full/minimal spec to reproduce the issue? -
Have you validated the input using an OpenAPI validator -
What's the version of OpenAPI Generator used? -
Have you search for related issues/PRs? -
What's the actual output vs expected output? -
[Optional] Bounty to sponsor the fix
Description
The asciidoc generator create path that cannot be interpreted by asciidoc processor:
-
the specDir and snippetDir attributes generated are not used in asciidoctor include directive
-
the path refers of included file can refers to path parameters wrote with curly braces, that is not supported by asciidoc processor.
openapi-generator version
openapi-generator@4.2.3 ( by dependency of openapi-generator-maven-plugin@4.2.3 )
OpenAPI declaration file content or url
files tree:
$: tree asciidoc
asciidoc/
├── api
│ ├── intro.adoc
│ └── resources
│ └── {id}
│ └── GET
│ ├── implementation.adoc
│ └── spec.adoc
└── snippet
└── resources
└── {id}
└── GET
├── GET.json
├── http-request.adoc
└── http-response.adoc
OAS file specification.json:
{
"openapi": "3.0.1",
"info": {
"title": "OpenAPI definition",
"version": "v0"
},
"servers": [
],
"paths": {
"/resources/{id}": {
"get": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "default response",
"content": {
"application/json;charset=UTF-8": {
"schema": {
"type": "string"
}
}
}
}
}
}
}
}
}
Command line used for generation
java -jar openapi-generator-cli.jar generate \
-i specification.json \
-g asciidoc \
-o /tmp/ \
-p specDir=asciidoc/api/ \
-p snippetDir=asciidoc/snippet/
Steps to reproduce
-
Reproduce the repository and file content. The adoc files can be empty.
-
Launch the command.
Related issues/PRs
the index.adoc generated:
= OpenAPI definition
team@openapitools.org
v0
:toc: left
:numbered:
:toclevels: 3
:source-highlighter: highlightjs
:keywords: openapi, rest, OpenAPI definition
:specDir: ./src/docs/asciidoc/api/
:snippetDir: ./src/docs/asciidoc/snippet/
...
[abstract]
...
include::intro.adoc[opts=optional]
...
===== Description
include::resources/{id}/GET/spec.adoc[opts=optional]
...
===== Samples
include::resources/{id}/GET/http-request.adoc[opts=optional]
include::resources/{id}/GET/http-response.adoc[opts=optional]
* wiremock data link:resources/{id}/GET/GET.json[]
...
===== Implementation
include::resources/{id}/GET/implementation.adoc[opts=optional]
The include paths do not include snippetDir and specDir attributes.
The include path should escape curly brackets of path parameters.
include::{specDir}intro.adoc[opts=optional] include::{specDir}resources/\{id\}/GET/spec.adoc[opts=optional] include::{snippetDir}resources/\{id\}/GET/http-request.adoc[opts=optional] include::{snippetDir}resources/\{id\}/GET/http-response.adoc[opts=optional] wiremock data link:{snippetDir}resources/\{id\}/GET/GET.json[] include::{specDir}resources/\{id\}/GET/implementation.adoc[opts=optional]
Suggest a fix
In AsciidocDocumentationCodegen.java:87 protect parameter path of relativeFileName and then add the attribute for the directory path.