2

我对Swagger很陌生，所以我可能有一些细节错误。Swagger 似乎是一个很酷的生成 REST 文档的工具。但是，我不喜欢它非常具有侵入性并且需要我在我的 java 类上添加注释。我发现这个名为swagger-jaxrs-doclet 的maven 插件似乎生成了这些 json 文件，我应该能够将这些文件传递给 swagger 以生成 swagger 文档。优点是我不需要在我的任何类上放大张旗鼓的注释。

不幸的是，swagger-jaxrs-doclet 文档没有告诉我下一步该做什么。有人可以告诉我如何获取 swagger-jaxrs-doclet 的输出并从中生成 swagger 文档吗？我需要在 Maven 中执行此操作。

4

3 回答 3

1

只需在某个本地服务器上上传 apidocs 或 dist 文件夹（基于您使用的 swagger-ui 版本）并从浏览器打开。javascript 被执行，您将看到输出。

于 2015-03-19T15:58:28.647 回答
1

查看https://github.com/teamcarma/swagger-jaxrs-doclet上的“使用部分” - 有关 maven 和 gradle 的示例。

此外，“示例”部分看起来很简单；因此有点不确定您正在寻求帮助的是什么。如果您可以再多一点-“有人可以告诉我如何获取 swagger-jaxrs-doclet 的输出并从中生成 swagger 文档吗？我需要在 maven 中执行此操作。”

据我了解，com.carma:swagger-doclet 会生成必要的 Swagger 1.2 资源描述文件，并将它们放在“build/reports/rest-api-docs”中，如果您只是按原样使用他们的示例。

于 2015-10-05T14:37:38.347 回答
0

我使用 gradle 为我的 java 项目设置它的方式如下：

1）。在 build.grade 中添加 doclet 配置

doclet(
      [group: 'com.carma', name: 'swagger-doclet', version: '1.0.4.2'],
      [group: 'javax.ws.rs', name: 'javax.ws.rs-api', version: '2.0']

)

2）。在构建任务 generateRestApiDocs(type: Javadoc) {

source = sourceSets.main.allJava
  def file = new File(project.rootDir.toString() + "/my-app/src/main/resources/assets/api-docs")

  destinationDir = file
  options.classpath = configurations.doclet.files.asType(List)
  options.docletpath = configurations.doclet.files.asType(List)
  options.doclet = "com.carma.swagger.doclet.ServiceDoclet"
  options.addStringOption("apiVersion", "1")
  options.addStringOption("docBasePath", "/assets/api-docs")
  options.addStringOption("apiBasePath", "../../")
  options.addBooleanOption("skipUiFiles", true)
  if (JavaVersion.current().isJava8Compatible()) {
    options.addStringOption('Xdoclint:none')
  }
 }

3）。使构建依赖于生成的其余文档任务

build.dependsOn generateRestApiDocs

4）。注释和 javadoc 你的资源

/**
   * Endpoint to do something blah blah
   *
   * @param id blah blah blah
   * @param boolean blah blah blahb
   * @return {@link blab}
   * @responseMessage 200 ok
   * @responseMessage 404 not found
   */
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  @Path("/{id}")

5）。构建任务将创建必要的 swagger json 文件，由您的 swagger ui 提供。

于 2015-04-15T18:38:47.130 回答