Swagger2Markup
The generated html has some error when ApiModel value contains slash(/)
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 /
@ApiModel("order/create_order")
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.adoc、definitions.adoc.
paths.adoc content is:
==== Parameters
[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Body**|**request** +
__required__|request|<<_create_order,create_order>>
|===
definitions.adoc content is:
[[_order_create_order]]
=== 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.
