在 swagger maven 插件配置中包含 info 对象答案

【问题标题】：Including info object in swagger maven plugin configuration在 swagger maven 插件配置中包含 info 对象
【发布时间】：2020-01-19 20:35:42
【问题描述】：

在我的 swagger 输出 json 文件中包含信息对象时遇到问题。我正在使用来自https://github.com/swagger-api/swagger-core 的 swagger-maven-plugin。这是我尝试过的...

我已经尝试在我的 pom.xml 中包含一个 info 对象，就像这样......

        <plugin>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-maven-plugin</artifactId>
        <version>2.0.9</version>
        <configuration>
            <outputFileName>openapi</outputFileName>
            <outputPath>${project.build.directory}/openapi-json</outputPath>
            <outputFormat>JSONANDYAML</outputFormat>
            <resourcePackages>
                <package>packageName</package>
            </resourcePackages>
            <info>
                <version>
                    1.0
                </version>
                <title>
                    Swagger Pet Sample App Config File
                </title>
                <description>
                This is a sample server Petstore server.  You can find out more about Swagger.                          
                </description>
                <termsOfService>http://swagger.io/terms/
                </termsOfService>
                <license>
                    <name>
                        Apache2.0
                    </name>
                    <url>
                        http://www.apache.org/licenses/LICENSE-2.0.html
                    </url>
                </license>  
                <contact>
                    <email>
                        george@aol.com
                    </email>
                </contact>
            </info>
            <prettyPrint>TRUE</prettyPrint>
        </configuration>
        <executions>
            <execution>
                <phase>compile</phase>
                <goals>
                    <goal>resolve</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

我还尝试在我的路径中添加一个 openapi-configuration.yaml 文件。该文件看起来像这样。我从插件 repo 自述文件页面复制了这个文件，所以内容与我上面的第一种方法不同。

    resourcePackages:
- packageName
prettyPrint: true
cacheTTL: 0
openAPI:
  info:
    version: '1.0'
    title: Swagger Pet Sample App Config File
    description: 'This is a sample server Petstore server.  You can find out more
      about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net,
      #swagger](http://swagger.io/irc/).  For this sample, you can use the api key
      `special-key` to test the authorizat ion filters.'
    termsOfService: http://swagger.io/terms/
    contact:
      email: apiteam@swagger.io
    license:
      name: Apache 2.0
      url: http://www.apache.org/licenses/LICENSE-2.0.html

这些方法都不起作用。

我错过了什么？干杯。

【问题讨论】：

标签： maven swagger openapi swagger-maven-plugin

【解决方案1】：

更新我得到这个工作如下...... 在我的 pom.xml...

            <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.0.9</version>                
            <configuration>
                <outputFileName>openapi</outputFileName>
                <outputPath>${project.build.directory}/openapi-json</outputPath>
                <outputFormat>JSONANDYAML</outputFormat>
                <resourcePackages>
                    <package>packageName.services</package>
                </resourcePackages>
                <configurationFilePath>${project.basedir}/openapi.yaml</configurationFilePath>              
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>resolve</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

然后在单独的配置 YAML 文件中...

  openAPI:
  info:
    version: '1.0'
    title: API Documentation
    description: 'This is documentation for the Foosite API. You can find out more about FooSite at FooSite.org.'
    termsOfService: http://foosite.org/terms/
    license:
      name: Apache2.0
      url: http://www.apache.org/licenses/LICENSE-2.0.html
    contact:
      email: george@aol.com
prettyPrint: true

【讨论】：

【解决方案2】：

在您的 JAX-RS 应用程序类中，使用 @OpenAPIDefinition 注释按照 OpenAPI Specification 的架构定义您的招摇信息：

package test.webapp.rest.application;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;
    
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.servers.Server;
import io.swagger.v3.oas.annotations.info.Info;
@ApplicationPath("/rest/*")
@OpenAPIDefinition(
            info = @Info(title="This is my title", 
            description="This is my description", version="9.9.9"), 
            servers = @Server(url="http://localhost:8080/test-webapp-rest/rest"))
public class RESTApplication extends Application{
    ...
}

在你的 pom.xml 中，将此 Application Class 的包添加到 swagger-maven-plugin 的“resourcePackages”中：

        <!-- GENERATE openapi.json in /src/main/webapp/swagger-ui-->
        <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.1.5</version>
            <configuration>
                <outputFileName>openapi</outputFileName>
                <outputPath>${basedir}/src/main/webapp/swagger-ui</outputPath>
                <outputFormat>JSONANDYAML</outputFormat>
                <resourcePackages>
                    <package>test.webapp.rest.application</package>
                    <package>test.webapp.rest.resource</package>
                </resourcePackages>
                <prettyPrint>TRUE</prettyPrint>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>resolve</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

第二步是在 JSON 或 YAML 中生成信息的基本步骤：

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "This is my title",
    "description" : "This is my description",
    "version" : "9.9.9"
  },
  "servers" : [ {
    "url" : "http://localhost:8080/test-webapp-rest/rest",
    "variables" : { }
  } ],
  ...
}


openapi: 3.0.1
info:
  title: This is my title
  description: This is my description
  version: 9.9.9
servers:
- url: http://localhost:8080/test-webapp-rest/rest
  variables: {}

【讨论】：

【解决方案3】：

“信息”标签应位于“apiSource”标签下，如下所示

<configuration>
    <apiSources>
        <apiSource>
            <springmvc>true</springmvc>
            <locations>com.xx.yyy.oooo</locations>
            <schemes>http,https</schemes>
            <host>@YYYY@</host>
            <basePath>@XXXX@</basePath>
            <info>

            </info>

【讨论】：