# swagger-parser: turning an OpenAPI document into swagger-core POJOs in Java

> Swagger Parser reads an OpenAPI 2.0 or 3.x definition in JSON or YAML and returns a swagger-core OpenAPI object together with validation messages. It is a Java library for applications that consume a specification at runtime rather than a code generator that emits a client.

**swagger-api/swagger-parser** — Swagger Spec to Java POJOs

- Repository: https://github.com/swagger-api/swagger-parser
- Website: http://swagger.io
- Stars: 870 · Forks: 566
- Language: Java
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/swagger-api-swagger-parser

## What the parser returns and why the result object matters

Swagger Parser turns an OpenAPI definition in JSON or YAML into the swagger-core representation, a Java POJO tree rooted at the OpenAPI class, and it hands back any validation warnings and errors it found along the way. The return type is not the OpenAPI object itself but a SwaggerParseResult, which is why even the simplest example checks for null before touching anything:

```java
import io.swagger.parser.OpenAPIParser;
import io.swagger.v3.parser.OpenAPIV3Parser;
import io.swagger.v3.parser.core.models.SwaggerParseResult;
import io.swagger.v3.oas.models.OpenAPI;

// ... your code

  // parse a swagger description from the petstore and get the result
  SwaggerParseResult result = new OpenAPIParser().readLocation("https://petstore3.swagger.io/api/v3/openapi.json", null, null);
```

That shape is the single most useful thing to know about the library. A parser that threw on the first bad reference would be easy to use and hard to deploy, because a minor spec typo on one operation would take down a service. Here, `result.getMessages()` is a list you can log or count, and `result.getOpenAPI()` can be null while the messages explain why. The README example prints those messages to standard error and then guards the object with a null check, which is the pattern to copy.

Two entry points exist for the common case. `OpenAPIParser.readLocation` reads from a URL or a file path, and `OpenAPIParser.readContents` reads from a string. The README shows the same petstore URL passed to each, with the file path variant commented in the file example, so the two differ only in where the bytes come from.

## OpenAPI 2.0 input is converted, and 3.0 only parsing is available separately

The library handles the awkward version split explicitly. If you pass an OpenAPI 2.0 document, the parser first converts it into a comparable OpenAPI 3.0 one, so downstream code sees one model shape regardless of the version on the wire. The README states this in one line: the 2.0 document will be first converted into a comparable OpenAPI 3.0 one.

If you want to skip that conversion and handle only 3.0 documents, `OpenAPIV3Parser` is the direct class, and it offers a shorter convenience call that returns the OpenAPI object rather than the wrapper:

```java
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");
```

The convenience call is tempting and it is exactly where validation feedback disappears, because there is no result object in that signature to hold messages. For a service that must report bad input back to the caller, the OpenAPIParser route with the result wrapper is the one to take.

Version support changed in a specific release. The README notes that since version 2.1.0 Swagger Parser supports OpenAPI 3.1, with details on a swagger-core wiki page. It also points users who need 1.X and OpenAPI 2.0 at a separate v1 branch of the repository. So the artifact you pick determines which specification dialects it can read, and mixing an old 1.X expectation with a 2.1.x dependency is the kind of mistake that shows up as a document that parses but has no paths.

## Adding it to a Maven build and building the source

The library is distributed through Maven central for releases and Sonatype OSS for snapshots, and the Maven coordinates are stable:

```xml
<dependency>
  <groupId>io.swagger.parser.v3</groupId>
  <artifactId>swagger-parser</artifactId>
  <version>2.1.48</version>
</dependency>
```

The README lists the prerequisites as Java 11 and Apache Maven 3.x, both needing to be installed and available in the path. Java 11 is the floor, and the repository carries a build badge for master against Java 11, 14 and 17.

If you want to work from a checkout, the build command is:

```
mvn package
```

That single step is what the README documents, and the repository layout backs up a multi-module Maven build with a top-level pom.xml and a modules directory. The CI directory and appveyor.yml alongside the GitHub Actions workflow show the project is built on more than one platform, which matters for a parser that has to behave identically on Windows and Linux.

Release cadence is steady and visible: v2.1.48 came out on 2026-08-31, v2.1.47 on 2026-08-18 and v2.1.46 on 2026-08-03. Those are point releases with a documentation-style changelog line rather than feature announcements, and the last push to the repository was on 2026-09-09. Nothing about the release notes suggests a deprecation cycle you have to schedule around.

## Protected specs, self-signed certificates and the TRUST_ALL switch

Because the parser can fetch a document over HTTP, it needs a way to authenticate, and it needs a way to cope with awkward TLS. Authentication is handled by passing AuthorizationValue objects. Each carries a key name, a value and a type, where the type is either header or query:

```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`
```

The list of these values is handed to `readWithInfo`, which takes the location and a list of authorization values, so you can pass several credentials at once.

The TLS side has a switch the README presents bluntly. For self-signed certificates, or certificates signed by GoDaddy, you can set an environment variable:

```
export TRUST_ALL=true
```

After that the parser ignores invalid certificates. The README calls it generally a bad idea and says it is for people working inside a firewall who know what they are doing. It is worth being precise about what the flag does, because it disables certificate validation for the fetch, and a specification fetched over an unauthenticated channel is an input you should treat as untrusted regardless of the source. A separate section covers Let's Encrypt certificates, which may not work by default on older Java versions, with the README noting that versions prior to 1.8u101 most likely require an additional CA in the JVM and that 1.8u101 on its own may not be enough.

## ParseOptions is where resolution behaviour lives

The library customizes parsing through a ParseOptions object rather than through many separate methods. The README introduces the options section with the line that the parser uses options as a way to customize the behavior while parsing, then shows the resolve option in code:

```java
ParseOptions parseOptions = new ParseOptions();
parseOptions.setResolve(true); 
final OpenAPI openAPI = new OpenAPIV3Parser().read("a.yaml", null, parseOptions);
```

The third argument to `read` is where the options go. The README table of contents lists four options, resolve, ResolveFully, Flatten and ResolveCombinators, and the body of the README is truncated in the section that would describe each of them in full, so the exact semantics of Flatten and ResolveCombinators cannot be stated from what is documented here. What the resolve example does show is the shape of the call and that the flags are setters on a single object rather than separate method overloads.

That matters when you write your own tests. If you have a spec with cross-file references, the difference between resolving and not resolving changes the object you get back, and it changes whether the validator reports a missing reference as an error or silently produces a partially resolved model. The right practice is to set the options explicitly in your test fixtures rather than relying on a default you have not read, and to assert on `result.getMessages()` so a broken reference fails the test instead of producing an empty path map.

## Where swagger-parser is the wrong choice

The clearest case is when you want generated client code. The project description says Swagger Spec to Java POJOs, but the POJOs in question are swagger-core models of the specification, not a typed client for the API being described. A POJO tree of paths, parameters and schemas is a description of a contract; it is not an SDK that serialises your payloads, retries a request or refreshes a token. For a client, a code generator built on the same swagger-core ecosystem is the tool that matches the job.

It is also the wrong shape for a build-time contract freeze where you want the model checked into your repository. The library is a runtime component: it reads and parses when your code calls it, so the parse cost, the HTTP fetch of the remote document, and the dependency on the spec staying reachable all sit on your runtime path.

The service-permission angle is the practical caveat. With `TRUST_ALL=true` the parser will accept an invalid certificate, which means a spec delivered by a compromised or misconfigured host is parsed as if it were legitimate. For an internal spec server with a known certificate, install the CA in the JVM instead of disabling validation.

Licensing is the easiest part of the decision. The repository carries an Apache-2.0 licence with LICENSE and NOTICE files, so you can use the parser inside a commercial product without the copyleft obligations that a GPL library would impose on a linked work.

## Conclusion

Swagger Parser fits a Java service that needs to consume an OpenAPI document it does not control, whether to route requests, validate payloads against a spec, or drive a contract test at runtime. It does not fit a team that wants a generated client library or static stubs, because it produces a model of the specification rather than an SDK for it. Before adopting it, check that your Java version is 11 or newer and Maven 3.x is on the path, pin the version you build against, and confirm whether you need OpenAPI 3.1 support, since that arrived in 2.1.0 while 1.X and OpenAPI 2.0 live on the separate v1 branch.

## FAQ

### What does swagger-parser produce from an OpenAPI document?

It parses a JSON or YAML OpenAPI definition into the swagger-core representation as a Java OpenAPI POJO, and returns a SwaggerParseResult holding that object together with validation warnings and errors.

### How do I add swagger-parser to a Maven project?

Add the io.swagger.parser.v3 groupId with the swagger-parser artifactId and a version such as 2.1.48 to your dependencies. The README requires Java 11 and Apache Maven 3.x on the path, and a checkout can be built with `mvn package`.

### Does swagger-parser support OpenAPI 3.1 and OpenAPI 2.0?

Since version 2.1.0 the parser supports OpenAPI 3.1, and an OpenAPI 2.0 document is first converted into a comparable OpenAPI 3.0 one. Users needing 1.X and OpenAPI 2.0 are pointed at the separate v1 branch.

### How do I parse a specification that requires authentication?

Build AuthorizationValue objects with a key name, a value and a type of header or query, then pass them in a list to readWithInfo together with the location of the document.

### How can I parse a spec served with a self-signed certificate?

The README says to set the TRUST_ALL environment variable so the parser ignores invalid certificates, and notes this is generally a bad idea except inside a firewall where you know what you are doing. The alternative is installing the certificate in the JVM keystore with keytool.

## Sources

- [License: Apache-2.0](https://github.com/swagger-api/swagger-parser/blob/master/LICENSE)
- [Project website](http://swagger.io)
- [README](https://github.com/swagger-api/swagger-parser/blob/master/README.md)
- [Releases](https://github.com/swagger-api/swagger-parser/releases)
- [swagger-api/swagger-parser on GitHub](https://github.com/swagger-api/swagger-parser)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/swagger-api-swagger-parser