flowchartsman edited a comment on issue #9200:
URL: https://github.com/apache/pulsar/issues/9200#issuecomment-759945918
For anyone following along, I have attempted to update the plugin to
openapi-tools/swagger-maven plugin v1.0.3, but the results have been
inconsistent and yet strangely similar. This plugin appears to require
multiple executions to generate multiple swagger specs, however it requires
including the project as a dependency, and, even when it works, I find the same
problem, only worse. Here's the profile I was testing with:
```xml
<profiles>
<profile>
<id>swagger</id>
<build>
<plugins>
<plugin>
<groupId>io.openapitools.swagger</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>1.0.3</version>
<dependencies>
<dependency>
<groupId>org.apache.pulsar</groupId>
<artifactId>pulsar-broker</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>swagger-admin</id>
<phase>compile</phase>
<configuration>
<swaggerConfig>
<basePath>/admin/v2</basePath>
<info>
<title>Pulsar Admin REST API</title>
<version>v2</version>
</info>
</swaggerConfig>
<outputDirectory>${basedir}/target/docs</outputDirectory>
<outputFilename>admin</outputFilename>
<outputFormats>
<outputFormat>JSON</outputFormat>
<outputFormat>YAML</outputFormat>
</outputFormats>
<resourcePackages>
<resourcePackage>org.apache.pulsar.broker.admin.v2</resourcePackage>
</resourcePackages>
</configuration>
<goals>
<goal>generate</goal>
</goals>
</execution>
<execution>
<id>swagger-function</id>
<phase>compile</phase>
<configuration>
<swaggerConfig>
<basePath>/admin/v3</basePath>
<info>
<title>Pulsar Function Admin REST API</title>
<version>v3</version>
</info>
</swaggerConfig>
<outputDirectory>${basedir}/target/docs</outputDirectory>
<outputFilename>function</outputFilename>
<outputFormats>
<outputFormat>JSON</outputFormat>
<outputFormat>YAML</outputFormat>
</outputFormats>
<resourcePackages>
<resourcePackage>org.apache.pulsar.broker.admin.v3</resourcePackage>
</resourcePackages>
</configuration>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
```
Worth noting: the spec for `function` was empty until I removed `Functions`
from the end of the `resourcePackage, so it makes a comprensive v3 route
instead of just for functions. And even then, here is the generated
`updateFunction` route:
```json
"put": {
"tags": [
"functions"
],
"summary": "Updates a Pulsar Function currently running in cluster
mode",
"operationId": "updateFunction",
"consumes": [
"multipart/form-data"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "tenant",
"in": "path",
"description": "The tenant of a Pulsar Function",
"required": true,
"type": "string"
},
{
"name": "namespace",
"in": "path",
"description": "The namespace of a Pulsar Function",
"required": true,
"type": "string"
},
{
"name": "functionName",
"in": "path",
"description": "The name of a Pulsar Function",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"originalRef": "InputStream",
"$ref": "#/definitions/InputStream"
}
},
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"originalRef": "FormDataContentDisposition",
"$ref": "#/definitions/FormDataContentDisposition"
}
},
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "body",
"name": "body",
"description": "<description snipped>",
"required": false,
"schema": {
"originalRef": "FunctionConfig",
"$ref": "#/definitions/FunctionConfig"
},
"x-examples": {
"application/json": "{\n \"inputs\":
persistent://public/default/input-topic,\n \"parallelism\": 4\n \"output\":
persistent://public/default/output-topic\n \"log-topic\":
persistent://public/default/log-topic\n \"classname\":
org.example.test.ExclamationFunction\n \"jar\":
java-function-1.0-SNAPSHOT.jar\n}"
}
},
{
"in": "body",
"name": "body",
"description": "The update options is for the Pulsar Function
that needs to be updated.",
"required": false,
"schema": {
"originalRef": "UpdateOptions",
"$ref": "#/definitions/UpdateOptions"
}
}
],
"responses": {
"403": {
"description": "The requester doesn't have admin permissions"
},
"400": {
"description": "Invalid request (The Pulsar Function doesn't
exist, etc.)"
},
"200": {
"description": "Pulsar Function successfully updated"
}
}
},
```
More of the same. Form params getting incorrectly generated as `body`.
We've about reached the end of things I can think to try. Will probably open
a new issue to track a (much larger) effort to migrate annotations to
OpenAPI3/swagger 2/`io.openapitools.swagger` v2.x.x
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
