服装加工厂网站建设方案计划书,局域网网站怎样做数据库,站长平台百度,精美网站制作公司input发送a.jax看到时间流逝如此之快#xff0c;真是太恐怖了#xff01; OpenAPI规范3.0.0是对Swagger规范的重大改进#xff0c;大部分已于一年前发布#xff0c;但工具赶上了一段时间。 但是#xff0c;随着最近Swagger Core 2.0.0的正式发布#xff0c;事情肯定会加速… input发送a.jax 看到时间流逝如此之快真是太恐怖了 OpenAPI规范3.0.0是对Swagger规范的重大改进大部分已于一年前发布但工具赶上了一段时间。 但是随着最近Swagger Core 2.0.0的正式发布事情肯定会加速。 为了证明这一点著名的JAX-RS 2.1实现Apache CXF是OpenAPI 3.0.0的最早采用者之一在今天的帖子中我们将了解一下JAX-RS 2.1 API可以多么容易从中受益。 与往常一样为了使事情变得简单我们将设计人员管理Web API其中仅包含少量支持它的资源这里没有什么太令人兴奋的。 POST /api/people
GET /api/people/{email}
GET /api/people
DELETE /api/people/{email} 我们的模型将包含单个Person类。 public class Person {private String email;private String firstName;private String lastName;
} 为了增加一点魔力我们将使用Spring Boot来使我们尽快启动并运行。 这样让我们开始填充依赖项假设我们使用Apache Maven进行构建管理。 dependencygroupIdorg.apache.cxf/groupIdartifactIdcxf-spring-boot-starter-jaxrs/artifactIdversion3.2.4/version
/dependency 在最新的3.2.x版本中 Apache CXF基于Swagger Core 2.0.0引入了一个专用于OpenAPI 3.0.0的新模块cxf-rt-rs-service-description-openapi-v3 。 dependencygroupIdorg.apache.cxf/groupIdartifactIdcxf-rt-rs-service-description-openapi-v3/artifactIdversion3.2.4/version
/dependencydependencygroupIdorg.webjars/groupIdartifactIdswagger-ui/artifactIdversion3.13.6/version
/dependency Swagger UI并不是必须存在的但这是探索API的非常有用和漂亮的工具如果在classpath中可用 Apache CXF会将其无缝集成到您的应用程序中我们将在稍后介绍 。 前提条件就位让我们做一些编码 在开始之前值得注意的是Swagger Core 2.0.0有很多方法可以为您的服务填充OpenAPI 3.0.0定义包括属性文件注释或以编程方式。 在这篇文章中我们将仅使用注释。 OpenAPIDefinition(info Info(title People Management API,version 0.0.1-SNAPSHOT,license License(name Apache 2.0 License,url http://www.apache.org/licenses/LICENSE-2.0.html))
)
ApplicationPath(api)
public class JaxRsApiApplication extends Application {
} 看起来非常简单 OpenAPIDefinition为我们所有的Web API设置了顶级定义。 移动到PeopleRestService我们只需添加Tag注释那么标签我们的API。 Path( /people )
Tag(name people)
public class PeopleRestService {// ...
} 太棒了到目前为止没有什么复杂的。 最棘手的部分从Web API操作定义开始因此让我们看一下第一个示例即获取所有人的操作。 Produces(MediaType.APPLICATION_JSON)
GET
Operation(description List all people, responses {ApiResponse(content Content(array ArraySchema(schema Schema(implementation Person.class))),responseCode 200)}
)
public CollectionPerson getPeople() {// ...
} 相当多的注释但总的来说看起来很干净直接。 让我们看一下另一个即通过其电子邮件地址查找此人的端点。 Produces(MediaType.APPLICATION_JSON)
Path(/{email})
GET
Operation(description Find person by e-mail, responses {ApiResponse(content Content(schema Schema(implementation Person.class)), responseCode 200),ApiResponse(responseCode 404, description Person with such e-mail doesnt exists)}
)
public Person findPerson(Parameter(description E-Mail address to lookup for, required true) PathParam(email) final String email) {// ...
} 同样通过电子邮件删除该人的操作看起来几乎是相同的。 Path(/{email})
DELETE
Operation(description Delete existing person,responses {ApiResponse(responseCode 204,description Person has been deleted),ApiResponse(responseCode 404, description Person with such e-mail doesnt exists)}
)
public Response deletePerson(Parameter(description E-Mail address to lookup for, required true ) PathParam(email) final String email) {// ...
} 太好了让我们总结一下最后一个可以说是最有趣的端点它增加了一个新人使用FormParam的选择纯粹是为了说明API的不同风格。 Consumes(MediaType.APPLICATION_FORM_URLENCODED)
Produces(MediaType.APPLICATION_JSON)
POST
Operation(description Create new person,responses {ApiResponse(content Content(schema Schema(implementation Person.class), mediaType MediaType.APPLICATION_JSON),headers Header(name Location),responseCode 201),ApiResponse(responseCode 409, description Person with such e-mail already exists)}
)
public Response addPerson(Context final UriInfo uriInfo,Parameter(description E-Mail, required true) FormParam(email) final String email, Parameter(description First Name, required true) FormParam(firstName) final String firstName, Parameter(description Last Name, required true) FormParam(lastName) final String lastName) {// ...
} 如果您有使用较旧的Swagger规范记录Web API的经验则可能会发现该方法非常熟悉但比较冗长或者更确切地说是形式化的。 这是规范领导和社区所做的巨大工作的结果以使其尽可能完整和可扩展。 已定义和记录了API现在该尝试一下了 不过缺少的部分是Spring配置在该配置中我们将初始化并公开我们的JAX-RS Web服务。 Configuration
EnableAutoConfiguration
ComponentScan(basePackageClasses PeopleRestService.class)
public class AppConfig {Autowired private PeopleRestService peopleRestService;Bean(destroyMethod destroy)public Server jaxRsServer(Bus bus) {final JAXRSServerFactoryBean factory new JAXRSServerFactoryBean();factory.setApplication(new JaxRsApiApplication());factory.setServiceBean(peopleRestService);factory.setProvider(new JacksonJsonProvider());factory.setFeatures(Arrays.asList(new OpenApiFeature()));factory.setBus(bus);factory.setAddress(/);return factory.create();}Beanpublic ServletRegistrationBean cxfServlet() {final ServletRegistrationBean servletRegistrationBean new ServletRegistrationBean(new CXFServlet(), /api/*);servletRegistrationBean.setLoadOnStartup(1);return servletRegistrationBean;}
} OpenApiFeature是这里的关键要素它负责所有集成和自省。 Spring Boot应用程序是完成图片的最后一步。 SpringBootApplication
public class Application {public static void main(String[] args) {SpringApplication.run(AppConfig.class, args);}
} 让我们立即构建并运行它 mvn clean package
java -jar target/jax-rs-2.1-openapi-0.0.1-SNAPSHOT.jar 启动应用程序后我们的Web API的OpenAPI 3.0.0规范应处于活动状态并可以JSON格式用于以下位置 http://localhost:8080/api/openapi.json 或使用YAML格式 http://localhost:8080/api/openapi.json 探索并使用我们的Web API会很棒吗 由于我们包含了Swagger UI依赖关系因此不必理会只需导航到http// localhost8080 / api / api-docsurl / api / openapi.json 特别要注意的是小图标Swagger UI会与您的API版本一起放置以暗示其符合OpenAPI 3.0.0规范。 这里只需要注意使用Spring Boot没有什么特别的。 如果您在OSGi容器中使用Apache CXF 例如例如Apache Karaf 则还可以与OpenAPI 3.0.0集成如果您对此主题感兴趣请查阅官方文档和示例 。 一切看起来都很简单但是如何从Swagger规范的旧版本迁移到OpenAPI 3.0.0 Apache CXF具有强大的功能 可以即时转换较旧的规范但总的来说 OpenApi.Tools门户是评估选项的正确位置。 您应该迁移到OpenAPI 3.0.0吗 老实说我相信您应该至少应该尝试进行试验但是请注意该工具还不够成熟请期盼一些障碍您可以通过提供补丁来克服这些障碍 。 但是无疑前程似锦 完整的项目资源可在Github上找到 。 翻译自: https://www.javacodegeeks.com/2018/05/moving-with-the-times-towards-openapi-v3-0-0-adoption-in-jax-rs-apis.htmlinput发送a.jax
