Swagger codegen：简单的 JAX-RS 示例

Question

我是新来的，我发现文档是零散的，至少可以说缺乏。我正在尝试使用 Swagger 注释来注释我的 JAX-RS 兼容类以静态生成多种语言和文档的客户端库（这是一个优点）。但是，我似乎找不到一个开箱即用的简单示例。

这是我非常简单的 REST 服务：

package com.mypack.rest;

import com.mypack.entity.Person;
import com.mypack.service.PeopleService;
import com.wordnik.swagger.annotations.*;

import javax.ws.rs.*;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriInfo;
import java.util.Collection;

@Path("/people")
@Api(value = "/people", description = "Manage people")
public class PeopleRestService {
  private final PeopleService peopleService;

  public PeopleRestService(PeopleService peopleService) {
    this.peopleService = peopleService;
  }

  @Produces({MediaType.APPLICATION_JSON})
  @GET
  @ApiOperation(value = "List all people", notes = "List all people using paging", response = Person.class, responseContainer = "List")
  public Collection<Person> getPeople(@ApiParam(value = "Page to fetch", required = true) @QueryParam("page") @DefaultValue("1") final int page) {
    return peopleService.getPeople(page, 5);
  }

  @Produces({MediaType.APPLICATION_JSON})
  @Path("/{email}")
  @GET
  @ApiOperation(value = "Find person by e-mail", notes = "Find person by e-mail", response = Person.class)
  @ApiResponses({
        @ApiResponse(code = 404, message = "Person with such e-mail doesn't exists")
  })
  public Person getPeople(@ApiParam(value = "E-Mail address to lookup for", required = true) @PathParam("email") final String email) {
    return peopleService.getByEmail(email);
  }

// and more methods ...
}

然后我有一个 scala 类来生成客户端库（根据 github 上的示例）：

import com.wordnik.swagger.codegen.BasicJavaGenerator

object JavaPeopleServiceCodegen extends BasicJavaGenerator {
  def main(args: Array[String]) = generateClient(args)

  override def templateDir = "Java"
  override def destinationDir = "src/main/java"
  override def invokerPackage = Some("com.mypack.client")
  override def modelPackage = Some("com.mypack.entity")
  override def apiPackage = Some("com.mypack.api")

  additionalParams ++= Map(
    "artifactId" -> "people-rest",
    "artifactVersion" -> "1.0.0",
    "groupId" -> "com.mypack")

  override def supportingFiles =
    List(
      ("apiInvoker.mustache", destinationDir + java.io.File.separator + invokerPackage.get.replace(".", java.io.File.separator) + java.io.File.separator, "ApiInvoker.java"),
      ("JsonUtil.mustache", destinationDir + java.io.File.separator + invokerPackage.get.replace(".", java.io.File.separator) + java.io.File.separator, "JsonUtil.java"),
      ("apiException.mustache", destinationDir + java.io.File.separator + invokerPackage.get.replace(".", java.io.File.separator) + java.io.File.separator, "ApiException.java"),
      ("pom.mustache", "", "pom.xml"))
}

现在当我尝试运行此文件时，我总是收到以下错误：

Exception in thread "main" java.lang.NoSuchMethodError: com.wordnik.swagger.model.SwaggerSerializers$.formats(Ljava/lang/String;)Lorg/json4s/Formats;
  at com.wordnik.swagger.codegen.Codegen.<init>(Codegen.scala:45)
  at com.wordnik.swagger.codegen.BasicGenerator.<init>(BasicGenerator.scala:44)
  at com.wordnik.swagger.codegen.BasicJavaGenerator.<init>(BasicJavaGenerator.scala:25)
  at JavaPeopleServiceCodegen$.<init>(JavaPeopleServiceCodegen.scala:3)

最后，在我的 pom 文件中，我有 javax.ws.rs、swagger 和 swagger-codegen 的依赖项。我不明白我是否遗漏了一些运行时依赖项（看起来不像），我的 scala 库是错误的（我安装了 scala 2.10.3，并且 swagger 依赖项是针对 2.10 编译的，应该是二进制兼容的）或者我还没有理解一些基本的“陷阱”。

有什么帮助吗？

Answer 1

问题是类名冲突。在 codegen 项目中有一个 SwaggerSerializers 类，在 Swagger 核心中有一个。所以发生的事情是编译器使用了其中一个，而另一个试图在运行时使用，因此缺少一个方法。

I've just sent a pull request 使用一种可能的重构来解决这个问题。