當前位置：首頁 > 编程资源 > 编程问答 >内容正文

编程问答

openapi_MicroProfile OpenAPI上的Swagger UI

發(fā)布時間：2023/12/3 编程问答 32 豆豆

生活随笔收集整理的這篇文章主要介紹了 openapi_MicroProfile OpenAPI上的Swagger UI 小編覺得挺不錯的,現(xiàn)在分享給大家,幫大家做個參考.

openapi

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

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

快速概述

應(yīng)用

首先，在擴展javax.ws.rs.core.Application的類中，添加有關(guān)您的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 {}

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

服務(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();}}

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

獲取openapi yaml

現(xià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的，并且可以手動將其添加到您的項目（見這個偉大的職位由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 。

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

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

個性化您的用戶界面

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

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

示例：將其添加到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的應(yīng)用程序服務(wù)器，請參閱Apiee

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