阐明数据模型文档答案

【问题标题】：Enunciate Data Model Documentaton阐明数据模型文档
【发布时间】：2014-04-16 14:44:19
【问题描述】：

我在多模块 maven 项目中使用 Enunciate。我使用的是 1.28 版，我只是将它用于 SOAP 服务的文档目的。

这适用于所有服务。 targetNamespace 和 endpointInterface 必须在 @WebService 注释中声明，一切正常。我得到了带有 wsdl/wadl/xsd/html 输出的 zip。

通过输出文件识别和发布所有 javadoc。

但是...如果没有但是...我不会在这里写...

所有数据模型文件都不会！我尝试了以下选项：

<api-import pattern="package.model.**" /> 
<modules>
    <spring-app disabled="true" />
    <docs docsDir="/docs" title="Web Service API" copyright="ME" />
    <!-- Disable all the client generation tools -->
    <basic-app disabled="true" />
    <c disabled="true" />
    <csharp disabled="true" />
    <java-client disabled="true" />
    <jaxws-client disabled="true" />
    <jaxws-ri disabled="true" />
    <jaxws-support disabled="true" />
    <jersey disabled="true" />
    <obj-c disabled="true" />
    <xml forceExampleJson="true" />
    <jaxws disabled="true" />
    <amf disabled="true" />
</modules>

模块未包含在 webarchive 中，但声明为依赖项：

<dependency>
   <groupId>package.model</groupId>
   <artifactId>model</artifactId>
   <version>${project.parent.version}</version>
   <scope>provided</scope>
</dependency>

数据模型中的 DTO 和 ENUMS 通常提供有：

@XmlType(namespace = "https://package/DTO")

还有关于类和属性的 Javadoc。

但我也在 getter 和 setter 上尝试了 Javadoc。

我什至从我的项目中的示例实现中尝试了一些 xml 注释：

@javax.xml.bind.annotation.XmlType(name = "socialGroup", namespace = "http://api.ifyouwannabecool.com/link")
@javax.xml.bind.annotation.XmlRootElement(name = "socialGroup", namespace = "http://api.ifyouwannabecool.com/link")

没有成功。 javadoc 不会像 SOAP 服务那样包含在 xsd/wsdl/html 文件中。

你有什么想法吗？

【问题讨论】：

标签： documentation javadoc datamodel enunciate

【解决方案1】：

如果类位于不同的 Maven 模块中，正如您在依赖项中声明的那样，您必须明确告诉 Enunciate “导入”它们以包含 JavaDoc。

假设您的模型类位于名为“org.mycompany.widgets.model”的包和名为“org.mycompany.gadgets.model”的包中。告诉 Enunciate 导入这样的内容：

<enunciate ...>
  ...
  <api-import pattern="org.mycompany.gadgets.model.**"/>
  <api-import pattern="org.mycompany.widgets.model.**"/>
  ...

【讨论】：

【解决方案2】：

请在类的顶部添加 @XmlRootElement，以便发音会使它们出现在数据模型文档中。

Example : 

@XmlRootElement
public class Foo{
....
}

【讨论】：

【解决方案3】：

我认为问题出在<scope>provided</scope>。如果类不存在于类路径中，则 enunciate 将无法找到它们。将其更改为 <scope>compile</scope> 以及 @XmlRootElement 注释，它应该可以工作。

【讨论】：