配置 Jersey 2 的 web.xml 以支持 Swagger/OpenAPI v3。

huangapple go评论65阅读模式
英文:

Configure Jersey 2 web.xml for Swagger/ OpenAPI v3

问题

我正在运行 Jersey 2.30.1 API,并且我想将 Swagger 文档升级到 OpenAPI v3。

在 pom.xml 中,我的新 Swagger 依赖项如下:

    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>swagger-ui</artifactId>
        <version>3.17.0</version>
    </dependency>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.0.2</version>
    </dependency>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2-servlet-initializer</artifactId>
        <version>2.0.2</version>
    </dependency>

之前(使用 swagger 1.5 和 swagger-ui 2.2.10-1),我在我的 web.xml 中配置了 Swagger:

    <servlet>
        <servlet-name>Jersey2Config</servlet-name>
        <servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
        <init-param>
            <param-name>api.version</param-name>
            <param-value>2.0</param-value>
        </init-param>
        <init-param>
            <param-name>swagger.api.basepath</param-name>
            <param-value>/api</param-value>
        </init-param>
        <load-on-startup>4</load-on-startup>
    </servlet>

现在我想要做相同的事情,但我找不到文档,说明是否以及如何可能实现。

如何在使用 OpenAPI v3 时在我的 web.xml 中定义 Swagger 基路径和 API 版本?
英文:

I am running a Jersey 2.30.1 API and I want to upgrade the Swagger documentation to OpenAPI v3.

My new swagger dependencies in the pom.xml look like this:

&lt;dependency&gt;
	    &lt;groupId&gt;org.webjars&lt;/groupId&gt;
	    &lt;artifactId&gt;swagger-ui&lt;/artifactId&gt;
        &lt;version&gt;3.17.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
        &lt;groupId&gt;io.swagger.core.v3&lt;/groupId&gt;
        &lt;artifactId&gt;swagger-jaxrs2&lt;/artifactId&gt;
        &lt;version&gt;2.0.2&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
        &lt;groupId&gt;io.swagger.core.v3&lt;/groupId&gt;
        &lt;artifactId&gt;swagger-jaxrs2-servlet-initializer&lt;/artifactId&gt;
        &lt;version&gt;2.0.2&lt;/version&gt;
&lt;/dependency&gt;

Previously (swagger 1.5 with swagger-ui 2.2.10-1), I had Swagger configured in my web.xml:

&lt;servlet&gt;
            &lt;servlet-name&gt;Jersey2Config&lt;/servlet-name&gt;
            &lt;servlet-class&gt;io.swagger.jersey.config.JerseyJaxrsConfig&lt;/servlet-class&gt;
            &lt;init-param&gt;
                &lt;param-name&gt;api.version&lt;/param-name&gt;
                &lt;param-value&gt;2.0&lt;/param-value&gt;
            &lt;/init-param&gt;
            &lt;init-param&gt;
                &lt;param-name&gt;swagger.api.basepath&lt;/param-name&gt;
                &lt;param-value&gt;/api&lt;/param-value&gt;
            &lt;/init-param&gt;
            &lt;load-on-startup&gt;4&lt;/load-on-startup&gt;
&lt;/servlet&gt;

I would like to do the same now, but I can't find a documentation, if and how that would be possible.

How can I define the swagger base path and API version in my web.xml with OpenAPI v3?

答案1

得分: 1

<pom.xml>:

    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>swagger-ui</artifactId>
        <version>3.52.1</version>
    </dependency>

    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.1.10</version>
    </dependency>

    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2-servlet-initializer</artifactId>
        <version>2.1.10</version>
    </dependency>

<web.xml>:

The Jersey2Config servlet is completely removed from web.xml.
The servlet configuration needs to be changed for the parameter `io.swagger.v3.jaxrs2.integration.resources`

<servlet>
    <servlet-name>my servlet</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
      <param-name>jersey.config.server.provider.packages</param-name>
      <param-value>my.package.to.scan, io.swagger.v3.jaxrs2.integration.resources</param-value>
    </init-param>
  </servlet>

Additional to web.xml a new file openapi.yaml has to be created under `src/main/webapp/WEB-INF`. This is responsible for creating the openapi.yaml/ openapi.json file which will be consumed by the swagger ui.

<openapi.yaml>:

prettyPrint: true
cacheTTL: 0
readAllResources: false /** Only show methods in swagger-ui that are annotated */
openAPI:
  info:
    version: '1.0'
    title: 'my application'
  servers:
    - url: '/my-application'

<swagger ui>:

...
window.onload = function() {

    const window.ui = SwaggerUIBundle({
        url: 'https://my-domain.com/my-application/openapi.json',
        dom_id: '#swagger-ui-container',
        docExpansion: 'none',
        defaultModelsExpandDepth: -1,
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout",
        apisSorter: "alpha",
        tagsSorter: "alpha",
        operationsSorter: "alpha",
        validatorUrl: null
      });
}
...
英文:

After playing around with this, my solution is basically like so.

pom.xml:

&lt;dependency&gt;
    &lt;groupId&gt;org.webjars&lt;/groupId&gt;
    &lt;artifactId&gt;swagger-ui&lt;/artifactId&gt;
    &lt;version&gt;3.52.1&lt;/version&gt;
&lt;/dependency&gt;

&lt;dependency&gt;
    &lt;groupId&gt;io.swagger.core.v3&lt;/groupId&gt;
    &lt;artifactId&gt;swagger-jaxrs2&lt;/artifactId&gt;
    &lt;version&gt;2.1.10&lt;/version&gt;
&lt;/dependency&gt;

&lt;dependency&gt;
    &lt;groupId&gt;io.swagger.core.v3&lt;/groupId&gt;
    &lt;artifactId&gt;swagger-jaxrs2-servlet-initializer&lt;/artifactId&gt;
    &lt;version&gt;2.1.10&lt;/version&gt;
&lt;/dependency&gt;

web.xml:

The Jersey2Config servlet is completely removed from web.xml.
The servlet configuration needs to be changed for the parameter io.swagger.v3.jaxrs2.integration.resources

&lt;servlet&gt;
    &lt;servlet-name&gt;my servlet&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.glassfish.jersey.servlet.ServletContainer&lt;/servlet-class&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;jersey.config.server.provider.packages&lt;/param-name&gt;
      &lt;param-value&gt;my.package.to.scan, io.swagger.v3.jaxrs2.integration.resources&lt;/param-value&gt;
    &lt;/init-param&gt;
  &lt;/servlet&gt;

Additional to web.xml a new file openapi.yaml has to be created under src/main/webapp/WEB-INF. This is responsible for creating the openapi.yaml/ openapi.json file which will be consumed by the swagger ui.

openapi.yaml:

prettyPrint: true
cacheTTL: 0
readAllResources: false /** Only show methods in swagger-ui that are annotated */
openAPI:
  info:
    version: &#39;1.0&#39;
    title: &#39;my application&#39;
  servers:
    - url: &#39;/my-application&#39;

swagger ui:

...
window.onload = function() {

	const window.ui = SwaggerUIBundle({
        url: &#39;https://my-domain.com/my-application/openapi.json&#39;,
        dom_id: &#39;#swagger-ui-container&#39;,
        docExpansion: &#39;none&#39;,
        defaultModelsExpandDepth: -1,
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: &quot;StandaloneLayout&quot;,
        apisSorter: &quot;alpha&quot;,
        tagsSorter: &quot;alpha&quot;,
        operationsSorter: &quot;alpha&quot;,
        validatorUrl: null
      });
}
...

huangapple
  • 本文由 发表于 2020年10月6日 15:52:42
  • 转载请务必保留本文链接:https://go.coder-hub.com/64221519.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定