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

The generated html has some error when ApiModel value contains slash(/) #355

ykgarfield opened this issue Dec 22, 2018 · 0 comments


Copy link

commented Dec 22, 2018

Error description

When ApiModel value contains slash(/), the generated adoc/md has some error.For example, a controller method:

@RequestMapping(value= "...", method = RequestMethod.POST)
@ApiOperation(value="...", notes="...")
public BaseResponse createOrder(@Valid @RequestBody Order request, BindingResult bindingResult) {
	return null;

The Order model:

// be aware, the value has a /
public class Order {

When I use asciidoctor-maven-plugin to generate html document, I find that the link can't jump to the header. As following figure:


So I want to find out what the problem is.I view the generated html souce, the key statement as following, I add some coments:

// the create_order href link is _create_order
<p><a href="#_create_order">create_order</a></p>

# this header id is _order_create_order, not  _create_order
<h3 id="_order_create_order">order/create_order</h3>

I also made a diagram to understand this better:


Next, I view the generated .adoc files, I searchcreate_order string in paths.adocdefinitions.adoc.

paths.adoc content is:

==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|**Body**|**request** +

definitions.adoc content is:

=== order/create_order

Obviously, the id is not same, create_order id is _create_order in paths.adoc, _order_create_order in definitions.adoc.So the generate html documet has some error, the link can't jump to the header.In addition, the request example can't generated.

So this leads to two problems:

  • Link(html) can't jump to header
  • Request/Response Examples can't generate

Error cause analysis

Link/Anchor jump error

Why this error happen, because I use spring-fox lib to do some work.I find that GenericRef has two properties, ref and simpleRef.Take the example(order/create_order) above, the ref is #/definitions/order/create_order, the simpleRef is create_order.the simpleRef don't contains order prffix, this may be the reason.So when generate link id, uniform use only one of simpleRef or ref.

Request/Response Examples can't generate

The Swagger#getDefinitions() method return Map<String, Model>, It contains /order/create_order, not contains create_order, so I think when generate examples, use the simpleRef to get Model from Map<String, Model>(will get null).If use ref(remove the #/definitions/ preffix) can get the Model object.So we can first use simpleRef, if can't not get Model, then use ref.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
1 participant
You can’t perform that action at this time.