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