openapi_MicroProfile OpenAPI上的Swagger UI

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 {

        @Inject
        private 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.0
    info:
      title: Example application
      contact:
        name: Phillip Kruger
        url: http://www.phillip-kruger.com
        email: phillip.kruger@phillip-kruger.com
      version: 1.0.0
    servers:
    - url: /example
      description: localhost
    tags:
    - name: Simulate some exeption
      description: Create some exception
    - name: Config Retrieval service
      description: Get the value for a certain config
    paths:
      /api/config/{key}:
        get:
          tags:
          - Config Retrieval service
          description: Get the value for this key
          operationId: getConfigValue
          parameters:
          - name: key
            in: path
            required: true
            style: simple
            schema:
              type: string
          responses:
            200:
              description: Successful, returning the value
      /api/exception:
        get:
          tags:
          - Simulate some exeption
          description: Throw an exeption
          operationId: doSomething
          responses:
            412:
              description: You made a mistake
    components: {}

添加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 Kruger
    openapi-ui.title=My awesome services
    openapi-ui.swaggerHeaderVisibility=hidden
    openapi-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