Question

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

不幸的是，swagger-jaxrs-doclet文档并没有告诉我下一步该怎么做。有人能告诉我如何获取swagger-jaxrs-doclet的输出并从中生成swagger文档吗？我需要在maven中这样做。

Answer 1

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

Answer 2

查看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”中，如果您只是按原样使用它们的示例。

Answer 3

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

1）。将doclet配置添加到build.grade

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）。创建gradle任务以在构建之后生成其余文档 task 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）。 make build取决于生成的rest docs任务

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提供。

如何使用swagger-jaxrs-doclet的输出生成swagger文档？

3 个答案: