outofcoffee / vertx-oas Goto Github PK

View Code? Open in Web Editor NEW

29.0 7.0 4.0 64 KB

Generates a Swagger/OpenAPI specification from a Vert.x Web Router.

Kotlin 97.14% Shell 2.86%

vertx vertx-web swagger openapi openapi3 openapi-spec openapi-documentation

vertx-oas's Introduction

vertx-oas

Generates a Swagger/OpenAPI specification from a Vert.x Web Router.

Usage

Assuming you're using Vert.x Web, use it with your Router as follows:

// your normal Vert.x Web Router with paths etc.
Router router = Router.router(vertx);
router.post("/users").handler( routingContext -> { /* etc... */ });
router.get("/users/:userId").handler( routingContext -> { /* etc... */ });

// publish the Swagger/OpenAPI specification to a URL
RouterSpecGenerator.publishApiDocs(router, "/api/spec");

In this example, the specification is published to /api/spec.

You can obtain YAML or JSON versions of the specification by adding the appropriate file extension.

For example, fetching /api/spec.yaml would produce:

openapi: "3.0.1"
info:
  title: "Vert.x APIs"
  description: "This specification was generated from a Vert.x Web Router."
paths:
  /users:
    post:
      parameters: []
  /users/{userId}:
    get:
      parameters:
      - name: "userId"
        required: true
        allowEmptyValue: false

Limitations

Doesn't understand regex paths
Doesn't know the type of path parameters
Doesn't know about request or response body models

Use in your project

Maven

Add repository:

<project>
...
  <repositories>
    <repository>
      <id>gatehillsoftware-snapshots</id>
      <name>Gatehill Software Snapshots</name>
      <url>https://s3-eu-west-1.amazonaws.com/gatehillsoftware-maven/snapshots</url>
    </repository>
    <repository>
      <id>sonatype-snapshots</id>
      <name>Sonatype OSS Snapshots</name>
      <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
  </repositories>
...
</project>

Add dependency:

<dependencies>
    ...
    <dependency>
        <groupId>com.gatehill.vertx-oas</groupId>
        <artifactId>vertx-oas</artifactId>
        <version>1.0.1</version>
    </dependency>
    ...
</dependencies>

Gradle

Add repository:

repositories {
    maven {
        url 'https://s3-eu-west-1.amazonaws.com/gatehillsoftware-maven/snapshots'
    }
    maven {
        url 'https://oss.sonatype.org/content/repositories/snapshots'
    }
}

Add dependency:

compile 'com.gatehill.vertx-oas:vertx-oas:1.0.1'

Build

If you'd like to build the code locally, follow these instructions.

Prerequisites

JDK8

Compile and test

./gradlew clean build

Publish

Publish to local Maven repository:

./gradlew publishToMavenLocal

Publish to remote Maven repository:

./gradlew publish

Contributing

Pull requests are welcome.
Please run ktlint on your branch.

Author

Pete Cornish ([email protected])

vertx-oas's People

Contributors

Stargazers

Watchers

Forkers

gabrielacosta hoschie alberttejada

vertx-oas's Issues

Could Not Resolve Dependencies

I tried building the example project and it's giving me this error:

[vma@victor-work ~/Backup/vertx-oas/examples/maven]$ mvn clean compile
...
[ERROR] Failed to execute goal on project example: Could not resolve dependencies for project com.gatehill.vertxoas:example:jar:1.0-SNAPSHOT: Failure to find io.swagger.parser.v3:swagger-parser:jar:2.0.0-SNAPSHOT in https://s3-eu-west-1.amazonaws.com/gatehillsoftware-maven/snapshots was cached in the local repository, resolution will not be reattempted until the update interval of gatehillsoftware-snapshots has elapsed or updates are forced -> [Help 1]

Inline code so it's easier to read:
[ERROR] Failed to execute goal on project example: Could not resolve dependencies for project com.gatehill.vertxoas:example:jar:1.0-SNAPSHOT: Failure to find io.swagger.parser.v3:swagger-parser:jar:2.0.0-SNAPSHOT in https://s3-eu-west-1.amazonaws.com/gatehillsoftware-maven/snapshots was cached in the local repository, resolution will not be reattempted until the update interval of gatehillsoftware-snapshots has elapsed or updates are forced -> [Help 1]

Generator only works if path has one HttpMethod

The generator will only include the last of the HttpMethod per path. E.g. can't do a get if you have a put/etc.

The bug is in this line in the OpenApiServiceImpl file.
paths.put(convertedPath, pathItem)

Since that is a map it replaces any prior key/value pair. One way to fix this might be for the pathItem param to be a list, then add to list.

However it appears that PathItem is supposed to hold all the Operations so if that's the case then it seems it needs to 'merge' with the prior one.

I changed the logic to get the PathItem from the map if it exists so that the new operation can be added to the existing PathItem. This fixed the issue for me.