swagger-parser

by swagger-api

swagger-api / swagger-parser

Swagger Spec to Java POJOs

435 Stars 373 Forks Last release: 8 days ago (v1.0.52) Apache License 2.0 2.1K Commits 77 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Swagger Parser

NOTE: If you're looking for

swagger-parser
1.X and OpenAPI 2.0, please refer to v1 branch

Build Status

Build Status

Build Status

Overview

This is the Swagger Parser project, which reads OpenAPI definitions into current Java POJOs. It also provides a simple framework to add additional converters from different formats into the Swagger objects, making the entire toolchain available.

Usage

Using the Swagger Parser is simple. Once included in your project, you can read a OpenAPI Specification from any location:

import io.swagger.v3.parser.OpenAPIV3Parser;
import io.swagger.v3.oas.models.OpenAPI;

// ... your code

// read a swagger description from the petstore

OpenAPI openAPI = new OpenAPIV3Parser().read("https://petstore3.swagger.io/api/v3/openapi.json");

You can read from a file location as well: ```java OpenAPI openAPI = new OpenAPIV3Parser().read("./path/to/openapi.yaml");

If your OpenAPI definition is protected, you can pass headers in the request:

```java import io.swagger.v3.parser.core.models.AuthorizationValue;

// ... your code

// build a authorization value AuthorizationValue mySpecialHeader = new AuthorizationValue() .keyName("x-special-access") // the name of the authorization to pass .value("i-am-special") // the value of the authorization .type("header"); // the location, as either header or query

// or in a single constructor AuthorizationValue apiKey = new AuthorizationValue("api_key", "special-key", "header"); OpenAPI openAPI = new OpenAPIV3Parser().readWithInfo( "https://petstore3.swagger.io/api/v3/openapi.json", Arrays.asList(mySpecialHeader, apiKey) );

Dealing with self-signed SSL certificates

If you're dealing with self-signed SSL certificates, or those signed by GoDaddy, you'll need to disable SSL Trust Manager. That's done by setting a system environment variable as such:

export TRUST_ALL=true

And then the Swagger Parser will ignore invalid certificates. Of course this is generally a bad idea, but if you're working inside a firewall or really know what you're doing, well, there's your rope.

Dealing with Let's Encrypt

Depending on the version of Java that you use, certificates signed by the Let's Encrypt certificate authority may not work by default. If you are using any version of Java prior to 1.8u101, you most likely must install an additional CA in your JVM. Also note that 1.8u101 may not be sufficient on it's own. Some users have reported that certain operating systems are not accepting Let's Encrypt signed certificates.

Your options include:

  • Accepting all certificates per above
  • Installing the certificate manually in your JVM using the keystore using the
    keytool
    command
  • Configuring the JVM on startup to load your certificate

But... this is all standard SSL configuration stuff and is well documented across the web.

Prerequisites

You need the following installed and available in your $PATH:

After cloning the project, you can build it from source with this command:

mvn package

Extensions

This project has a core artifact--

swagger-parser
, which uses Java Service Provider Inteface (SPI) so additional extensions can be added.

To build your own extension, you simply need to create a

src/main/resources/META-INF/services/io.swagger.parser.SwaggerParserExtension
file with the full classname of your implementation. Your class must also implement the
io.swagger.parser.SwaggerParserExtension
interface. Then, including your library with the
swagger-parser
module will cause it to be triggered automatically.

Adding to your project

You can include this library from Sonatype OSS for SNAPSHOTS, or Maven central for releases. In your dependencies:

  io.swagger.parser.v3
  swagger-parser
  2.0.22

Security contact

Please disclose any security-related issues or vulnerabilities by emailing [email protected], instead of using the public issue tracker.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.