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進行構建管理）。

<dependency><groupId>org.apache.cxf</groupId><artifactId>cxf-spring-boot-starter-jaxrs</artifactId><version>3.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 。

<dependency><groupId>org.apache.cxf</groupId><artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId><version>3.2.4</version> </dependency><dependency><groupId>org.webjars</groupId><artifactId>swagger-ui</artifactId><version>3.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 Collection<Person> 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 doesn't 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 doesn't 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：// localhost：8080 / api / api-docs？url = / 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.html

input發送a.jax

總結

以上是生活随笔為你收集整理的input发送a.jax_与时俱进：在JAX-RS API中采用OpenAPI v3.0.0的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。