MicroProfile OpenApi為我們提供了一種使用OpenApi 3描述我們JAX-RS API的標(biāo)準(zhǔn)化方法。如果您以前使用過swagger-jaxrs和swagger-annotations ，由于OpenApi是基于Swagger構(gòu)建的，因此您會(huì)感到非常熟悉。

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

快速概述

應(yīng)用

首先，在擴(kuò)展javax.ws.rs.core.Application的類中，添加有關(guān)API的標(biāo)頭信息：

@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 {}

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

服務(wù)

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

• @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();}}

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

獲取openapi yaml

現(xiàn)在，如果您運(yùn)行應(yīng)用程序，則可以轉(zhuǎn)到/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的快速概述。 在此處了解更多信息：

• 規(guī)格
• Github

最新?lián)P鞭UI適用于OpenAPI的，并且可以手動(dòng)將其添加到您的項(xiàng)目（見這個(gè)偉大的職位由Hayri奇切克 ），或者你可以使用這個(gè) ，它會(huì)自動(dòng)將其添加有用的庫(kù)：

在您的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 。

僅添加上述內(nèi)容便已經(jīng)為您提供了默認(rèn)的UI，例如：

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

個(gè)性化您的用戶界面

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

• openapi-ui.copyrightBy –在頁(yè)腳中為版權(quán)添加名稱。 默認(rèn)為無(wú)。
• openapi-ui.copyrightYear –添加版權(quán)年份。 默認(rèn)為當(dāng)前年份。
• openapi-ui.title –在窗口中添加標(biāo)題。 默認(rèn)為“ MicroProfile – Open API”。
• openapi-ui.serverInfo –在服務(wù)器上添加信息。 默認(rèn)為系統(tǒng)服務(wù)器信息。
• openapi-ui.contextRoot –添加上下文根。 默認(rèn)為當(dāng)前值。
• openapi-ui.swaggerUiTheme –使用swagger-ui-themes中的主題。 默認(rèn)為“ flattop”。
• openapi-ui.swaggerHeaderVisibility –顯示/隱藏swagger徽標(biāo)標(biāo)題。 默認(rèn)為“可見”。
• openapi-ui.exploreFormVisibility –顯示/隱藏瀏覽表單。 默認(rèn)為“隱藏”。
• openapi-ui.serverVisibility –顯示/隱藏服務(wù)器選擇。 默認(rèn)為“隱藏”。
• openapi-ui.createdWithVisibility –顯示/隱藏創(chuàng)建的頁(yè)腳。 默認(rèn)為“可見”。

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

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

會(huì)改變用戶界面：

主題

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

openapi-ui.swaggerUiTheme=monokai

商標(biāo)

最后，您可以通過在/src/main/resources/包含一個(gè)名為openapi.png的文件來(lái)將徽標(biāo)更改為公司徽標(biāo)：

蜂鳥

對(duì)于不具有MicroProfile的應(yīng)用程序服務(wù)器，請(qǐng)參閱Apiee

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

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎(jiǎng)勵(lì)來(lái)咯，堅(jiān)持創(chuàng)作打卡瓜分現(xiàn)金大獎(jiǎng)

總結(jié)

以上是生活随笔為你收集整理的MicroProfile OpenAPI上的Swagger UI的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。