openapi

MicroProfile OpenApi為我們提供了一種使用OpenApi 3描述我們JAX-RS API的標準化方法。如果您以前使用過swagger-jaxrs和swagger- 批注 ，由于OpenApi是基于Swagger構建的，因此您會感到非常熟悉。

2015年11月5日，SmartBear與3Scale，Apigee，Capital One，Google，IBM，Intuit，Microsoft，PayPal和Restlet聯合宣布成立Open API Initiative，這是Linux基金會下的一個開源項目。 作為OAI形成的一部分，SmartBear向Linux基金會捐贈了Swagger規范，這意味著OpenAPI規范在語義上與以前稱為Swagger 2.0規范的規范完全相同 – www.openapis.org/faq

快速概述

應用

首先，在擴展javax.ws.rs.core.Application的類中，添加有關您的API的標頭信息：

@ApplicationPath("/api")@OpenAPIDefinition(info = @Info(title = "Example application", version = "1.0.0", contact = @Contact(name = "Phillip Kruger", email = "phillip.kruger@phillip-kruger.com",url = "http://www.phillip-kruger.com")),servers = {@Server(url = "/example",description = "localhost")})public class ApplicationConfig extends Application {}

（ 在此處查看完整的示例）

服務

然后在您的服務中，添加描述您的服務的注釋：

• @Tag
• @Operation
• @APIResponse
• 等等

例：

@RequestScoped@Path("/config")@Tag(name = "Config Retrieval service", description = "Get the value for a certain config")public class ConfigRetrievalService {@Injectprivate Config config;@GET @Path("/{key}")@Operation(description = "Get the value for this key")@APIResponses({@APIResponse(responseCode = "200", description = "Successful, returning the value")})@Produces(MediaType.TEXT_PLAIN)public Response getConfigValue(@PathParam("key") String key) {String value = config.getValue(key, String.class);log.log(Level.INFO, "{0} = {1}", new Object[]{key, value});return Response.ok(value).build();}}

（見完整的例子在這里 ，另一個（富勒）例如這里 ）

獲取openapi yaml

現在，如果您運行您的應用程序，則可以轉到/openapi以獲取yaml：

openapi: 3.0.0info:title: Example applicationcontact:name: Phillip Krugerurl: http://www.phillip-kruger.comemail: phillip.kruger@phillip-kruger.comversion: 1.0.0servers:- url: /exampledescription: localhosttags:- name: Simulate some exeptiondescription: Create some exception- name: Config Retrieval servicedescription: Get the value for a certain configpaths:/api/config/{key}:get:tags:- Config Retrieval servicedescription: Get the value for this keyoperationId: getConfigValueparameters:- name: keyin: pathrequired: truestyle: simpleschema:type: stringresponses:200:description: Successful, returning the value/api/exception:get:tags:- Simulate some exeptiondescription: Throw an exeptionoperationId: doSomethingresponses:412:description: You made a mistakecomponents: {}

添加Swagger UI

上面是MicroProfile OpenAPI的快速概述。 在此處了解更多信息：

• 規范
• Github

最新揚鞭UI適用于OpenAPI的，并且可以手動將其添加到您的項目（見這個偉大的職位由Hayri奇切克 ），或者你可以使用這個 ，它會自動將其添加有用的庫：

在您的pom.xml ：

<dependency><groupId>com.github.phillip-kruger.microprofile-extensions</groupId><artifactId>openapi-ext</artifactId><version>1.0.9</version></dependency>

這將通過webjars插入 Swagger UI，并從您可以使用MicroProfile Config API配置的模板生成index.html 。

僅添加上述內容便已經為您提供了默認的UI，例如：

http：// localhost：8080 / example / api / openapi-ui /

個性化您的用戶界面

使用Config API，您可以個性化UI。 這是您可以使用的配置鍵：

• openapi-ui.copyrightBy –在頁腳中為版權添加名稱。 默認為無。
• openapi-ui.copyrightYear –添加版權年份。 默認為當前年份。
• openapi-ui.title –在窗口中添加標題。 默認為“ MicroProfile – Open API”。
• openapi-ui.serverInfo –在服務器上添加信息。 默認為系統服務器信息。
• openapi-ui.contextRoot –添加上下文根。 默認為當前值。
• openapi-ui.swaggerUiTheme –使用swagger-ui-themes中的主題。 默認為“ flattop”。
• openapi-ui.swaggerHeaderVisibility –顯示/隱藏swagger徽標標題。 默認為“可見”。
• openapi-ui.exploreFormVisibility –顯示/隱藏瀏覽表單。 默認為“隱藏”。
• openapi-ui.serverVisibility –顯示/隱藏服務器選擇。 默認為“隱藏”。
• openapi-ui.createdWithVisibility –顯示/隱藏創建的頁腳。 默認為“可見”。

示例：將其添加到META-INF/microprofile.properties

openapi-ui.copyrightBy=Phillip Krugeropenapi-ui.title=My awesome servicesopenapi-ui.swaggerHeaderVisibility=hiddenopenapi-ui.serverVisibility=visible

會改變用戶界面：

主題

默認的UI使用swagger-ui-themes中的flattop主題，但是您也可以更改它：

openapi-ui.swaggerUiTheme=monokai

商標

最后，您可以通過在/src/main/resources/包含一個名為openapi.png的文件來將徽標更改為公司徽標：

蜂鳥

對于沒有MicroProfile的應用程序服務器，請參閱Apiee

翻譯自: https://www.javacodegeeks.com/2018/08/swagger-ui-microprofile-openapi.html

openapi

總結

以上是生活随笔為你收集整理的openapi_MicroProfile OpenAPI上的Swagger UI的全部內容，希望文章能夠幫你解決所遇到的問題。

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