经典重庆网站,济南公司,使用apmserv本地搭建多个网站,重庆网上房地产网站随着JAX-RS API的发展#xff0c;以及今年早些时候在JSR-339下发布的2.0版本#xff0c;使用出色的Java平台创建REST服务变得更加容易。 但是#xff0c;极大的简化带来了巨大的责任#xff1a;记录所有这些API#xff0c;以便其他开发人员可以快速了解如何使用它们。 不… 随着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 doesnt 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 Persons first name, required true ) private String email;ApiModelProperty( value Persons e-mail address, required true ) private String firstName;ApiModelProperty( value Persons 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// localhost8080 / 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.setDefaultUseCachesfalse的一个重要说明因为我们正在从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// localhost8080 / swagger / 最后一点关于Swagger还有很多话要说但是我希望这个简单的示例能够显示出使我们的REST服务具有自文档化的功能并且只需很少的工作即可轻松使用。 非常感谢Wordnik团队。 源代码可在Github上获得 。 参考 Swagger让开发人员喜欢在我们的JCG合作伙伴 Andrey Redko {devmind}博客上使用您的REST API 。 翻译自: https://www.javacodegeeks.com/2013/10/swagger-make-developers-love-working-with-your-rest-api.html