随着JAX-RS API的发展，以及今年早些时候在JSR-339下发布的2.0版本，使用出色的Java平台创建REST服务变得更加容易。

但是，极大的简化带来了巨大的责任：记录所有这些API，以便其他开发人员可以快速了解如何使用它们。 不幸的是，在这方面开发人员只能靠自己： JSR-339并没有太大帮助。 可以肯定的是，从源代码生成冗长且易于遵循的文档，而不是要求某人在开发过程中编写它，真是太棒了。 听起来不真实，对吧？ 在某种程度上确实如此，但是帮助以Swagger的形式出现。

本质上， Swagger做的是一件简单但非常强大的事情：通过添加一些附加注释，它会生成REST API描述（ HTTP方法，路径/查询/表单参数，响应， HTTP错误代码等），甚至提供了一个简单的Web UI来玩对您的API的REST调用（更不用说所有这些元数据也可以通过REST获得）。

在深入研究实现细节之前，让我们快速看一下Swagger来自API消费者预期的含义。 假设您已经开发了一种出色的REST服务来管理人员。 作为良好的公民，此REST服务具有完整的功能，并提供以下功能：

• 列出所有人（ GET ）
• 通过电子邮件查找人（ GET ）
• 添加新人（ POST ）
• 更新现有人员（ PUT ）
• 最后删除人（ DELETE ）

从Swagger的角度来看，这是相同的API：

看起来很漂亮。 让我们做更多的事情，并从Swagger UI调用我们的REST服务，这真棒。 最复杂的用例是添加新人（ POST ），因此将仔细研究这一情况。

如您在上面的快照中所见，每一个REST服务调用都存在：

• 服务说明
• 相对语境路径
• 参数（形式/路径/查询），必需或可选
• HTTP状态码： 201 CREATED和409 CONFLICT
• 准备出发尝试一下！ 立即调用REST服务（具有开箱即用的参数验证功能）

为了完成演示部分，让我展示另一个示例，其中涉及REST资源（在我们的例子中，这是一个简单的Person类）。 Swagger能够提供其属性和有意义的描述以及预期的响应内容类型。

看起来不错！ 转到下一部分，所有内容都与实现细节有关。 Swagger支持与JAX-RS服务的无缝集成，在现有注释的顶部仅需几个附加注释。 首先，在我们的示例中，应该记录的每个单个JAX-RS服务都应使用@Api注释进行注释：

@Path( "/people" ) 
@Api( value = "/people", description = "Manage people" )
public class PeopleRestService {// ...
}

接下来，相同的方法适用于REST服务操作：应该记录的每个方法都应使用@ApiOperation批注（可选）并使用@ ApiResponses / @ ApiResponse进行批注 。 如果它接受参数，则应使用@ApiParam批注进行批注。 这里有几个例子：

@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 ) {// ...
}

还有一个：

@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 ) {// ...
}

REST资源类（或模型类）需要特殊的注释： @ApiModel和@ApiModelProperty 。 这是我们的Person类的样子：

@ApiModel( value = "Person", description = "Person resource representation" )
public class Person {@ApiModelProperty( value = "Person's first name", required = true ) private String email;@ApiModelProperty( value = "Person's e-mail address", required = true ) private String firstName;@ApiModelProperty( value = "Person's last name", required = true ) private String lastName;// ...
}

最后一步是将Swagger插入JAX-RS应用程序。 我开发的示例使用Spring Framework ， Apache CXF ， Swagger UI和嵌入式Jetty （完整项目可在Github上找到 ）。 集成Swagger只需添加配置bean（ swaggerConfig ），一个附加的JAX-RS服务（ apiListingResourceJson ）和两个JAX-RS提供程序（ resourceListingProvider和apiDeclarationProvider ）即可。

package com.example.config;import java.util.Arrays;import javax.ws.rs.ext.RuntimeDelegate;import org.apache.cxf.bus.spring.SpringBus;
import org.apache.cxf.endpoint.Server;
import org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.DependsOn;
import org.springframework.core.env.Environment;import com.example.resource.Person;
import com.example.rs.JaxRsApiApplication;
import com.example.rs.PeopleRestService;
import com.example.services.PeopleService;
import com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider;
import com.wordnik.swagger.jaxrs.config.BeanConfig;
import com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider;
import com.wordnik.swagger.jaxrs.listing.ApiListingResourceJSON;
import com.wordnik.swagger.jaxrs.listing.ResourceListingProvider;@Configuration
public class AppConfig {public static final String SERVER_PORT = "server.port";public static final String SERVER_HOST = "server.host";public static final String CONTEXT_PATH = "context.path";  @Bean( destroyMethod = "shutdown" )public SpringBus cxf() {return new SpringBus();}@Bean @DependsOn( "cxf" )public Server jaxRsServer() {JAXRSServerFactoryBean factory = RuntimeDelegate.getInstance().createEndpoint( jaxRsApiApplication(), JAXRSServerFactoryBean.class );factory.setServiceBeans( Arrays.< Object >asList( peopleRestService(), apiListingResourceJson() ) );factory.setAddress( factory.getAddress() );factory.setProviders( Arrays.< Object >asList( jsonProvider(), resourceListingProvider(), apiDeclarationProvider() ) );return factory.create();}@Bean @Autowiredpublic BeanConfig swaggerConfig( Environment environment ) {final BeanConfig config = new BeanConfig();config.setVersion( "1.0.0" );config.setScan( true );config.setResourcePackage( Person.class.getPackage().getName() );config.setBasePath( String.format( "http://%s:%s/%s%s",environment.getProperty( SERVER_HOST ),environment.getProperty( SERVER_PORT ),environment.getProperty( CONTEXT_PATH ),jaxRsServer().getEndpoint().getEndpointInfo().getAddress() ) );return config;}@Beanpublic ApiDeclarationProvider apiDeclarationProvider() {return new ApiDeclarationProvider();}@Beanpublic ApiListingResourceJSON apiListingResourceJson() {return new ApiListingResourceJSON();}@Beanpublic ResourceListingProvider resourceListingProvider() {return new ResourceListingProvider();}@Bean public JaxRsApiApplication jaxRsApiApplication() {return new JaxRsApiApplication();}@Bean public PeopleRestService peopleRestService() {return new PeopleRestService();}// ... 
}

为了摆脱任何可能的硬编码配置，所有参数都通过命名属性（ SERVER_PORT ， SERVER_HOST和CONTEXT_PATH ）传递。 Swagger公开了其他REST端点来提供API文档，在我们的示例中，可以通过以下网址访问它： http：// localhost：8080 / rest / api / api-docs 。 Swagger UI使用它，它本身已嵌入最终的JAR存档中，并由Jetty用作静态Web资源。

最后一个难题是启动嵌入式Jetty容器，该容器将所有这些部件粘合在一起并封装到Starter类中：

package com.example;import org.apache.cxf.transport.servlet.CXFServlet;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.handler.HandlerList;
import org.eclipse.jetty.servlet.DefaultServlet;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;
import org.eclipse.jetty.util.resource.Resource;
import org.springframework.core.io.ClassPathResource;
import org.springframework.web.context.ContextLoaderListener;
import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;import com.example.config.AppConfig;public class Starter {private static final int SERVER_PORT = 8080;private static final String CONTEXT_PATH = "rest";public static void main( final String[] args ) throws Exception {Resource.setDefaultUseCaches( false );final Server server = new Server( SERVER_PORT );  System.setProperty( AppConfig.SERVER_PORT, Integer.toString( SERVER_PORT ) );System.setProperty( AppConfig.SERVER_HOST, "localhost" );System.setProperty( AppConfig.CONTEXT_PATH, CONTEXT_PATH );    // Configuring Apache CXF servlet and Spring listener  final ServletHolder servletHolder = new ServletHolder( new CXFServlet() );      final ServletContextHandler context = new ServletContextHandler();   context.setContextPath( "/" );context.addServlet( servletHolder, "/" + CONTEXT_PATH + "/*" );     context.addEventListener( new ContextLoaderListener() ); context.setInitParameter( "contextClass", AnnotationConfigWebApplicationContext.class.getName() );context.setInitParameter( "contextConfigLocation", AppConfig.class.getName() );// Configuring Swagger as static web resourcefinal ServletHolder swaggerHolder = new ServletHolder( new DefaultServlet() );final ServletContextHandler swagger = new ServletContextHandler();swagger.setContextPath( "/swagger" );swagger.addServlet( swaggerHolder, "/*" );swagger.setResourceBase( new ClassPathResource( "/webapp" ).getURI().toString() );final HandlerList handlers = new HandlerList();handlers.addHandler( context );handlers.addHandler( swagger );server.setHandler( handlers );server.start();server.join(); }
}

几点评论使事情变得更加清晰：我们的JAX-RS服务将在/ rest / *上下文路径下可用，而Swagger UI在/ swagger上下文路径下可用。 关于Resource.setDefaultUseCaches（false）的一个重要说明：因为我们正在从JAR文件提供静态Web内容，所以必须将此属性设置为false作为此bug的解决方法。

现在，让我们通过输入以下内容来构建并运行我们的JAX-RS应用程序：

mvn clean package
java -jar target/jax-rs-2.0-swagger-0.0.1-SNAPSHOT.jar

稍后，您的浏览器中将提供Swagger UI ， 网址为： http：// localhost：8080 / swagger /

最后一点，关于Swagger还有很多话要说，但是我希望这个简单的示例能够显示出使我们的REST服务具有自文档化的功能，并且只需很少的工作即可轻松使用。 非常感谢Wordnik团队。

• 源代码可在Github上获得 。

翻译自: https://www.javacodegeeks.com/2013/10/swagger-make-developers-love-working-with-your-rest-api.html