Swagger Parser

https://github.com/swagger-api/swagger-parser
Admin
Swagger Parser parses OpenAPI definitions in JSON or YAML format into Java POJO representation with...
Tokens:228,820
Snippets:1,204
Trust Score:9.3
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### resolveExample(Map<String,Example> examples)

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-resolution.md

Merges #/components/examples/... examples into the given map.

```APIDOC
## resolveExample(Map<String,Example> examples)

### Description
Merges `#/components/examples/...` examples into the given map.

### Method
```java
public Map<String,Example> resolveExample(Map<String,Example> examples)
```

### Parameters
- **examples** (Map<String,Example>) - Required - The map of examples to resolve.

### Returns
- **Map<String,Example>** - The resolved map of examples.

```

--------------------------------

### ResolveFully Example Files

Source: https://github.com/swagger-api/swagger-parser/blob/master/README.md

Example input files a.yaml and b.yaml demonstrating reference structure.

```yaml
openapi: 3.0.1
paths:
  "/newPerson":
    post:
      summary: Create new person
      description: Create new person
      responses:
        '200':
          description: ok
          content:
            "*/*":
              schema:
                "$ref": "./ref-without-component/b.yaml#/components/schemas/CustomerType"
```

```yaml
openapi: 3.0.1
components:
  schemas:
    CustomerType:
      type: string
      example: Example value
```

--------------------------------

### AuthorizationValue Usage Examples

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/core-models.md

Examples demonstrating fluent initialization, constructor usage, URL-scoped credentials, and passing them to OpenAPIV3Parser.

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

// fluent
AuthorizationValue header = new AuthorizationValue()
        .keyName("x-api-key")
        .value("abc123")
        .type("header");

// constructor
AuthorizationValue apiKey = new AuthorizationValue("api_key", "special-key", "query");

// scoped to one host
AuthorizationValue scoped = new AuthorizationValue("token", "t", "header",
        url -> url.getHost().equals("secure.example.com"));

List<AuthorizationValue> auths = List.of(header, apiKey, scoped);
SwaggerParseResult result = new OpenAPIV3Parser()
        .readLocation("https://secure.example.com/openapi.yaml", auths, null);
```

--------------------------------

### Basic Usage Example

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-resolution.md

Example of using InlineModelResolver via ParseOptions with OpenAPIV3Parser.

```APIDOC
## Basic Usage Example

### Description
Example of using InlineModelResolver via ParseOptions with OpenAPIV3Parser.

### Code
```java
import io.swagger.v3.parser.OpenAPIV3Parser;
import io.swagger.v3.parser.core.models.ParseOptions;
import io.swagger.v3.oas.models.OpenAPI;

ParseOptions options = new ParseOptions();
options.setFlatten(true);                       // OpenAPIV3Parser runs InlineModelResolver

OpenAPI openAPI = new OpenAPIV3Parser().read("flatten.yaml", null, options);
System.out.println(openAPI.getComponents().getSchemas().keySet());
// e.g. [inline_response_200, ...]
```
```

--------------------------------

### ParseOptions Configuration Example

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/core-models.md

Java example showing how to configure ParseOptions and use it with OpenAPIV3Parser to read an OpenAPI document.

```APIDOC
## ParseOptions Configuration Example

### Description
Demonstrates how to create and configure ParseOptions for parsing an OpenAPI document with resolution and flattening options.

### Method
N/A (Java code example)

### Endpoint
N/A

### Parameters
#### ParseOptions setters
- **setResolve(boolean)** - Required - Resolve remote/relative $refs into components.
- **setResolveFully(boolean)** - Required - Additionally remove all local references, inlining referenced content.
- **setResolveCombinators(boolean)** - Optional - When true (default), merge allOf/anyOf/oneOf members into a single schema; when false, keep composed schemas structure.
- **setExplicitObjectSchema(boolean)** - Optional - When true (default), set unspecified property type to object; when false, leave undefined.
- **setFlatten(boolean)** - Required - Move inline schemas into components/schemas and replace with local refs.
- **setSafelyResolveURL(boolean)** - Optional - Run PermittedUrlsChecker on remote refs for SSRF protection.
- **setRemoteRefAllowList(List<String>)** - Optional - Glob host[:port] patterns for URL resolution allow list.
- **setRemoteRefBlockList(List<String>)** - Optional - Glob host[:port] patterns for URL resolution block list.

### Request Example
```java
import io.swagger.v3.parser.core.models.ParseOptions;

ParseOptions options = new ParseOptions();
options.setResolve(true);
options.setResolveFully(true);
options.setResolveCombinators(false);   // keep allOf members intact
options.setExplicitObjectSchema(false); // don't force type: object
options.setFlatten(true);
options.setSafelyResolveURL(true);
options.setRemoteRefAllowList(List.of("petstore.example.com"));
options.setRemoteRefBlockList(List.of("internal.example.com"));

SwaggerParseResult result = new OpenAPIV3Parser().read("api.yaml", null, options);
```

### Response
#### Success Response
- **result** (SwaggerParseResult) - The parsed OpenAPI document result.

#### Response Example
N/A (no explicit response example provided)
```

--------------------------------

### Examples of using read methods

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/OpenAPIV3Parser.md

Two examples showing how to use the read method: one to read a remote OpenAPI spec and another to read a local file with full resolution enabled.

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

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

ParseOptions options = new ParseOptions();
options.setResolveFully(true);
OpenAPI dereferenced = new OpenAPIV3Parser().read("a.yaml", null, options);
```

--------------------------------

### processRefToExternalExample

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/processors.md

Processes an external example reference, loading the example, copying it into components, and returning a new local reference.

```APIDOC
## processRefToExternalExample

### Description
Processes an external example reference, loading the example, copying it into components, and returning a new local reference.

### Method
processRefToExternalExample

### Signature
`public String processRefToExternalExample(String $ref, RefFormat refFormat)`

### Parameters
- **$ref** (String) - Required - The external reference string.
- **refFormat** (RefFormat) - Required - The format of the reference.

### Returns
- **String** - The new local reference or the original $ref on failure.

### Behavior
- Loads the example via the cache.
- Copies it into components.
- Returns the new local ref.
- Emits a warning log if the loaded entity is null.

### Example
```java
String localRef = processor.processRefToExternalExample("./examples.yaml#/components/examples/PetExample", RefFormat.RELATIVE);
```
```

--------------------------------

### Advanced Usage Example

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-resolution.md

Example of direct use of InlineModelResolver with naming control.

```APIDOC
## Advanced Usage Example

### Description
Example of direct use of InlineModelResolver with naming control.

### Code
```java
import io.swagger.v3.parser.util.InlineModelResolver;

InlineModelResolver resolver = new InlineModelResolver(true, true, false);
resolver.flatten(openAPI);

// manual model creation
io.swagger.v3.oas.models.media.Schema model = openAPI.getComponents().getSchemas().get("inline_response_200");
String generated = resolver.uniqueName("inline_response_200"); // may return "inline_response_200_1"
Schema ref = resolver.makeRefProperty("#/components/schemas/" + generated, model);
```
```

--------------------------------

### Example of using parseJsonNode

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/OpenAPIV3Parser.md

Example showing how to parse a JsonNode tree using parseJsonNode.

```java
import com.fasterxml.jackson.databind.JsonNode;
import io.swagger.v3.parser.OpenAPIV3Parser;
import io.swagger.v3.parser.core.models.SwaggerParseResult;

JsonNode tree = /* a parsed JsonNode tree */;
SwaggerParseResult result = new OpenAPIV3Parser().parseJsonNode("inline", tree);
```

--------------------------------

### Original flatten.yaml example

Source: https://github.com/swagger-api/swagger-parser/blob/master/README.md

The source YAML file used to demonstrate the flattening process.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                 type: object
                 properties:
                    id:
                      type: integer
                      format: int64
                    name:
                      type: string
                    tag:
                      type: string
```

--------------------------------

### Verify URL with PermittedUrlsChecker

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/safe-url-resolver.md

Example of initializing a PermittedUrlsChecker with allowlist and denylist patterns and verifying a URL.

```java
import io.swagger.v3.parser.urlresolver.PermittedUrlsChecker;
import io.swagger.v3.parser.urlresolver.exceptions.HostDeniedException;
import io.swagger.v3.parser.urlresolver.models.ResolvedUrl;

PermittedUrlsChecker checker = new PermittedUrlsChecker(
        java.util.List.of("api.example.com:443"),   // allowlist (host[:port] globs)
        java.util.List.of("*.forbidden.example"));  // denylist

try {
    ResolvedUrl allowed = checker.verify("https://api.example.com/v1/openapi.json");
    System.out.println(allowed.getUrl());       // https://<resolved-ip>/v1/openapi.json
    System.out.println(allowed.getHostHeader()); // api.example.com
} catch (HostDeniedException e) {
    System.err.println(e.getMessage());          // e.g. "IP is restricted. URL [...]"
}
```

--------------------------------

### loadRef usage examples

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/ResolverCache.md

Demonstrates loading external and internal references using the loadRef method.

```java
import io.swagger.v3.parser.ResolverCache;
import io.swagger.v3.parser.models.RefFormat;
import io.swagger.v3.oas.models.media.Schema;

ResolverCache cache = new ResolverCache(openApi, null, "root.yaml");

// external schema ref
Schema pet = cache.loadRef("./models.yaml#/components/schemas/Pet", RefFormat.RELATIVE, Schema.class);

// internal ref from the in-memory document
Schema local = cache.loadRef("#/components/schemas/Pet", RefFormat.INTERNAL, Schema.class);
if (local == null) {
    // key not present in components (cast/load failure)
}
```

--------------------------------

### Java example using PermittedUrlsChecker with allowlist and denylist

Source: https://github.com/swagger-api/swagger-parser/blob/master/modules/swagger-parser-safe-url-resolver/README.md

Example usage of PermittedUrlsChecker with allowlist and denylist. The verify method throws HostDeniedException for private IPs not in the allowlist or for denylisted hosts, and returns a ResolvedUrl with the IP-replaced URL and host header for allowed public URLs.

```java
import io.swagger.v3.parser.urlresolver.PermittedUrlsChecker;
import io.swagger.v3.parser.urlresolver.exceptions.HostDeniedException;
import io.swagger.v3.parser.urlresolver.models.ResolvedUrl;

import java.util.List;

public class Main {
    public static void main() {
        List<String> allowlist = List.of("mysite.local");
        List<String> denylist = List.of("*.example.com:443");
        var checker = new PermittedUrlsChecker(allowlist, denylist);

        try {
            // Will throw a HostDeniedException as `localhost`  
            // resolves to local IP and is not in allowlist
            checker.verify("http://localhost/example");

            // Will return a ResolvedUrl if `github.com` 
            // resolves to a public IP
            checker.verify("https://github.com/swagger-api/swagger-parser");

            // Will throw a HostDeniedException as `*.example.com` is 
            // explicitly deny listed, even if it resolves to public IP
            checker.verify("https://subdomain.example.com/somepage");

            // Will return a `ResolvedUrl` as `mysite.local` 
            // is explicitly allowlisted
            ResolvedUrl resolvedUrl = checker.verify("http://mysite.local/example");
            System.out.println(resolvedUrl.getUrl()); // "http://127.0.0.1/example"
            System.out.println(resolvedUrl.getHostHeader()); // "mysite.local"
        } catch (HostDeniedException e) {
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### DereferencerContext Usage Example

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/reference-dereferencing.md

Example showing how to construct a DereferencerContext and use it with the DereferencersFactory to perform manual 3.1 dereferencing.

```java
import io.swagger.v3.parser.reference.*;

SwaggerParseResult parsed = new OpenAPIV3Parser().readContents(spec31, null, null);

DereferencerContext context = new DereferencerContext(parsed, null, "local",
        new ParseOptions(), null, null, true);

DereferencersFactory.getInstance().getDereferencers()
        .iterator().next().dereference(context, java.util.Collections.emptyIterator());
// parsed.getOpenAPI() is now dereferenced; messages appended to parsed.getMessages()
```

--------------------------------

### Example usage of SwaggerInventory

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/SwaggerInventory.md

Shows how to create an inventory from a v2 Swagger model and print counts and parameter details. Note that process methods do not throw declared exceptions and process(Property) may add null if ArrayProperty.getItems() is null.

```java
import io.swagger.models.Swagger;
import io.swagger.v3.parser.converter.SwaggerInventory;

SwaggerInventory inventory = new SwaggerInventory().process(swaggerV2Model);

System.out.println(inventory.getOperations().size() + " operations");
System.out.println(inventory.getModels().size() + " definitions");
for (io.swagger.models.parameters.Parameter p : inventory.getParameters()) {
    System.out.println(p.getName() + " / " + p.getIn());
}
```

--------------------------------

### OpenAPI 3.0.1 Schema Example

Source: https://github.com/swagger-api/swagger-parser/blob/master/README.md

A sample OpenAPI 3.0.1 specification demonstrating the use of allOf for composed models.

```yaml
openapi: 3.0.1
info:
  title: testing source file
  description: This is a sample server Petstore
  termsOfService: http://swagger.io/terms/
  version: 1.0.0
servers:
- url: http://petstore.swagger.io/api
paths:
  /withInvalidComposedModel:
    post:
      operationId: withInvalidComposedModel
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
              - required:
                - street
                type: object
                properties:
                  street:
                    type: string
                    example: 12345 El Monte Road
                  city:
                    type: string
                    example: Los Altos Hills
                  state:
                    type: string
                    example: CA
                  zip:
                    type: string
                    example: "94022"
              - required:
                - gps
                type: object
                properties:
                  gps:
                    type: string
        required: false
      responses:
        200:
          description: success!
components:
  schemas:
    ExtendedAddress:
      type: object
      allOf:
      - required:
        - street
        type: object
        properties:
          street:
            type: string
            example: 12345 El Monte Road
          city:
            type: string
            example: Los Altos Hills
          state:
            type: string
            example: CA
          zip:
            type: string
            example: "94022"
      - required:
        - gps
        type: object
        properties:
          gps:
            type: string
    Address:
      required:
      - street
      type: object
      properties:
        street:
          type: string
          example: 12345 El Monte Road
        city:
          type: string
          example: Los Altos Hills
        state:
          type: string
          example: CA
        zip:
          type: string
          example: "94022"
```

--------------------------------

### Running the Built-in 3.1 Dereferencer

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/reference-dereferencing.md

Example of using the OpenAPIV3Parser with ParseOptions to trigger the built-in 3.1 dereferencer.

```java
import io.swagger.v3.parser.OpenAPIV3Parser;
import io.swagger.v3.parser.core.models.ParseOptions;
import io.swagger.v3.parser.core.models.SwaggerParseResult;
import io.swagger.v3.parser.reference.*;

ParseOptions options = new ParseOptions();
options.setResolve(true);

SwaggerParseResult result = new OpenAPIV3Parser().readContents(spec31WithRefs, null, options);
// "resolve: true" already ran the dereferencer for 3.1 documents
System.out.println(result.getOpenAPI().getComponents().getSchemas().keySet());
```

--------------------------------

### Implementing a custom SwaggerParserExtension

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/core-models.md

Example implementation of the SwaggerParserExtension interface. Consumers must register their implementation using a META-INF/services file.

```java
package com.example;

import io.swagger.v3.parser.core.extensions.SwaggerParserExtension;
import io.swagger.v3.parser.core.models.*;

public class MyFormatExtension implements SwaggerParserExtension {
    @Override
    public SwaggerParseResult readLocation(String url, List<AuthorizationValue> auth, ParseOptions options) {
        return readContents(fetch(url), auth, options);
    }
    @Override
    public SwaggerParseResult readContents(String s, List<AuthorizationValue> auth, ParseOptions options) {
        SwaggerParseResult result = new SwaggerParseResult();
        if (s == null) return SwaggerParseResult.ofError("null");
        result.setOpenAPI(myConverter.toOpenAPI(s));
        return result;
    }
}
```

--------------------------------

### Accessing cache contents

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/ResolverCache.md

Example of retrieving the resolution and rename caches from a ResolverCache instance.

```java
import io.swagger.v3.parser.OpenAPIResolver;

OpenAPIResolver resolver = new OpenAPIResolver(openApi, null, "root.yaml");
ResolverCache cache = resolver.getCache();                 // getCache() on the resolver
// or: new ResolverCache(openApi, null, "root.yaml")

System.out.println(cache.getResolutionCache().keySet());   // refs already resolved
System.out.println(cache.getRenameCache());                // original -> renamed
```

--------------------------------

### loadRef error handling

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/ResolverCache.md

Example of catching a RuntimeException when providing an invalid reference format.

```java
try {
    cache.loadRef("bad#ref#too", RefFormat.URL, Schema.class);
} catch (RuntimeException e) {
    // "Invalid ref format: bad#ref#too"
}
```

--------------------------------

### Custom traverse with AbstractVisitor

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/reference-traverser.md

Shows how to run a custom traversal with an AbstractVisitor. Parses a spec, builds a DereferencerContext with local resolution, and uses OpenAPI31Traverser to rewrite external $refs to local component references. The visitor's visitSchema method is called for each schema; the example prints the resulting path keys.

```java
import io.swagger.v3.parser.reference.*;
import io.swagger.v3.parser.core.models.ParseOptions;
import io.swagger.v3.parser.core.models.SwaggerParseResult;
import io.swagger.v3.oas.models.media.Schema;
import java.util.List;

SwaggerParseResult parsed = new OpenAPIV3Parser().readContents(spec31, null, null);

DereferencerContext context = new DereferencerContext(parsed, null, "local",
        new ParseOptions(), null, null, true);
OpenAPI31Traverser traverser = new OpenAPI31Traverser(context);

io.swagger.v3.oas.models.OpenAPI out = traverser.traverse(parsed.getOpenAPI(),
        new AbstractVisitor() {
            @Override public Schema visitSchema(Schema schema, List<String> inheritedIds) {
                if (schema.get$ref() != null && schema.get$ref().startsWith("http")) {
                    schema.set$ref("#/components/schemas/" + nameOf(schema.get$ref()));
                }
                return schema;
            }
        });
System.out.println(out.getPaths().keySet());
```

--------------------------------

### Handle Denied URLs and Restricted Ranges

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/safe-url-resolver.md

Examples of how the checker handles URLs that are explicitly blocked or resolve to restricted IP ranges.

```java
try {
    checker.verify("https://internal.corp/private.yaml");
} catch (HostDeniedException e) { /* explicit denylist / restricted IP */ }

try {
    checker.verify("http://127.0.0.1/api.yaml");
} catch (HostDeniedException e) { /* IP is restricted. URL [http://127.0.0.1/api.yaml] */ }
```

--------------------------------

### Example: createJson() and createYaml() with duplicate key detection

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/ObjectMapperFactory.md

Example usage of ObjectMapperFactory to create JSON and YAML mappers. It demonstrates that reading a JSON document with duplicate keys ({"a":1,"a":2}) throws a JsonProcessingException with message "Duplicate field 'a'..." due to strict duplicate detection.

```java
import io.swagger.v3.parser.ObjectMapperFactory;
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper json = ObjectMapperFactory.createJson();
ObjectMapper yaml = ObjectMapperFactory.createYaml();

// strict duplicate detection: reading {"a":1,"a":2} fails
try {
    json.readTree("{\"a\":1,\"a\":2}");
} catch (com.fasterxml.jackson.core.JsonProcessingException e) {
    System.err.println(e.getOriginalMessage()); // "Duplicate field 'a'..."
}
```

--------------------------------

### Programmatic use of readFromLocation

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/cli.md

Java example showing how to call SwaggerParser.readFromLocation with a Namespace built from a HashMap, then print any validation messages.

```java
import io.swagger.v3.parser.SwaggerParser;
import net.sourceforge.argparse4j.inf.Namespace;
import java.util.HashMap;
import java.util.List;

Namespace ns = new Namespace(new HashMap<>() {{
    put("i", "./openapi.yaml");
    put("resolve", "true");
    put("o", "./out.yaml");
}});

List<String> messages = SwaggerParser.readFromLocation(ns);
if (!messages.isEmpty()) {
    messages.forEach(System.err::println);   // validation messages / parse errors
}
```

--------------------------------

### Build project from source

Source: https://github.com/swagger-api/swagger-parser/blob/master/README.md

Use the Maven package command to build the project after cloning.

```bash
mvn package
```

--------------------------------

### RefUtils.computeRefFormat

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-refs.md

Determines the RefFormat for a given reference string. It returns URL for http/https, INTERNAL for refs starting with '#/', RELATIVE for refs starting with '.' or '/' or containing '#/', and INTERNAL otherwise.

```APIDOC
## RefUtils.computeRefFormat

### Description
Determines the RefFormat for a given reference string. It returns URL for http/https, INTERNAL for refs starting with '#/', RELATIVE for refs starting with '.' or '/' or containing '#/', and INTERNAL otherwise.

### Method
computeRefFormat

### Signature
`public static RefFormat computeRefFormat(String ref)`

### Parameters
- **ref** (String) - Required - The reference string to analyze.

### Returns
- **RefFormat** - The computed reference format.
```

--------------------------------

### Configure ParseOptions for OpenAPI parsing

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/core-models.md

Demonstrates how to instantiate and configure ParseOptions to control resolution, flattening, and security settings for remote references.

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

ParseOptions options = new ParseOptions();
options.setResolve(true);
options.setResolveFully(true);
options.setResolveCombinators(false);   // keep allOf members intact
options.setExplicitObjectSchema(false); // don't force type: object
options.setFlatten(true);
options.setSafelyResolveURL(true);
options.setRemoteRefAllowList(List.of("petstore.example.com"));
options.setRemoteRefBlockList(List.of("internal.example.com"));

SwaggerParseResult result = new OpenAPIV3Parser().read("api.yaml", null, options);
```

--------------------------------

### ReferenceValidator.examples.validateComponent

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-refs.md

Validates whether a given reference exists in the examples component map.

```APIDOC
## ReferenceValidator.examples.validateComponent

### Description
Checks if the provided reference key exists in the `examples` component map.

### Method
`validateComponent(Components components, String reference)`

### Parameters
- **components** (Components) - Required - The Components object containing the component maps.
- **reference** (String) - Required - The reference key to check for existence.

### Return Value
- **boolean** - `true` if the reference exists in the `examples` map, `false` otherwise.
```

--------------------------------

### main(String[] args)

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/cli.md

The CLI entry point that parses command-line arguments and invokes the parser. It accepts flags for input file, resolution, flattening, output format, and error logging.

```APIDOC
## main(String[] args)

### Description
CLI entry point for the SwaggerParser. Parses command-line arguments and runs the parser accordingly.

### Method
main

### Parameters
#### Command-line Arguments
- **-i** (String) - Required - Input file to be parsed.
- **-resolve** (Boolean) - Optional - Resolve remote or local references. Default: false.
- **-resolveFully** (Boolean) - Optional - Resolve fully. Default: false.
- **-flatten** (Boolean) - Optional - Flatten the document. Default: false.
- **-o** (String) - Optional - Output file for parsed result.
- **-l** (String) - Optional - Output error logs to file.
- **-json** (Boolean) - Optional - Generate file as JSON. Default: false.
- **-yaml** (Boolean) - Optional - Generate file as YAML. Default: false.

### Request Example
java -cp swagger-parser-cli.jar io.swagger.v3.parser.SwaggerParser -i ./openapi.yaml -resolve -o ./resolved.yaml

### Response
#### Success Response
- **messages** (List<String>) - Parse/validation messages. Empty on success.

#### Response Example
[]
```

--------------------------------

### Calling processors directly

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/processors.md

Shows how to instantiate and run ComponentsProcessor, PathsProcessor, and OperationProcessor on an OpenAPI object. Requires an OpenAPI instance and a ResolverCache with a root file name and parse options.

```java
import io.swagger.v3.parser.*;
import io.swagger.v3.parser.processors.*;
import io.swagger.v3.parser.core.models.ParseOptions;
import io.swagger.v3.oas.models.OpenAPI;

OpenAPI openApi = readOpenApiSomehow();
ResolverCache cache = new ResolverCache(openApi, null, "root.yaml", new java.util.HashSet<>(),
        new ParseOptions());

new ComponentsProcessor(openApi, cache).processComponents();
new PathsProcessor(cache, openApi).processPaths();
// per-operation:
for (io.swagger.v3.oas.models.Operation op : openApi.getPaths().values().stream()
        .flatMap(p -> p.readOperations().stream()).toList()) {
    new OperationProcessor(cache, openApi).processOperation(op);
}
```

--------------------------------

### deserialize(JsonNode rootNode, String path, ParseOptions options, boolean isOaiAuthor)

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/OpenAPIDeserializer.md

Full entry point for deserialization. Stores the base path and root node, builds a ParseResult with options, calls parseRoot, and returns the result. On exception, returns a result with the error message.

```APIDOC
## deserialize(JsonNode rootNode, String path, ParseOptions options, boolean isOaiAuthor)

### Description
Full entry point for deserialization. Stores the base path and root node, builds a ParseResult with options, calls parseRoot, and returns the result. On exception, returns a result with the error message.

### Method
public SwaggerParseResult deserialize(JsonNode rootNode, String path, ParseOptions options, boolean isOaiAuthor)

### Parameters
- **rootNode** (JsonNode) - Required - The root node of the OpenAPI document to deserialize.
- **path** (String) - Optional - The base path used for resolving relative references.
- **options** (ParseOptions) - Required - Parse options controlling validation behavior.
- **isOaiAuthor** (boolean) - Required - Whether the document is authored by the OAI.

### Returns
- **SwaggerParseResult** - The result containing the parsed OpenAPI object and any validation messages. getOpenAPI() returns null if the document has no valid openapi version field or an exception occurred.
```

--------------------------------

### SwaggerParseResult Methods

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/core-models.md

Methods for setting and getting messages, OpenAPI object, and OpenAPI 3.1 flag.

```APIDOC
## SwaggerParseResult Methods

### Description
Methods for setting and getting messages, OpenAPI object, and OpenAPI 3.1 flag.

### Methods
- **messages(List<String> messages)** - Fluent setter returning this.
- **getMessages()** - Returns validation warnings/errors; null when none recorded.
- **setMessages(List<String> messages)** - Setter.
- **message(String message)** - Appends one message (lazily creates the list).
- **addMessages(List<String> messages)** - Appends a list.
- **getOpenAPI()** - Returns parsed OpenAPI POJO, or null on hard failure.
- **setOpenAPI(OpenAPI openAPI)** - Setter.
- **setOpenapi31(boolean openapi31)** - Setter for the 3.1 flag.
- **openapi31(boolean openapi31)** - Fluent setter.
- **isOpenapi31()** - Returns true when the document declares openapi: 3.1.x.

### Example
```java
SwaggerParseResult result = new OpenAPIV3Parser().readLocation("bad.yaml", null, null);
if (result.getOpenAPI() == null) {
    result.getMessages().forEach(System.err::println);
    return;
}
boolean is31 = result.isOpenapi31();
System.out.println(result.getOpenAPI().getSpecVersion());
```
```

--------------------------------

### ClasspathHelper.loadFileFromClasspath method

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-refs.md

Loads a resource as a string from the classpath using multiple classloader strategies. It normalizes separators to Unix style and throws a RuntimeException on I/O errors or if the file is missing.

```java
public static String loadFileFromClasspath(String location)
```

--------------------------------

### Validate component reference using ReferenceValidator

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-refs.md

Example usage of the ReferenceValidator.schemas constant to check if a specific schema key exists within the provided components.

```java
import io.swagger.v3.parser.util.ReferenceValidator;
import io.swagger.v3.oas.models.Components;

boolean ok = ReferenceValidator.schemas.validateComponent(components, "Pet"); // true if key exists
```

--------------------------------

### PermittedUrlsChecker(List<String> allowlist, List<String> denylist)

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/safe-url-resolver.md

Creates a PermittedUrlsChecker with the given allowlist and denylist. Null lists are treated as empty lists and compiled into UrlPatternMatchers.

```APIDOC
## PermittedUrlsChecker(List<String> allowlist, List<String> denylist)

### Description
Creates a PermittedUrlsChecker with the given allowlist and denylist. Null lists are treated as empty lists and compiled into UrlPatternMatchers.

### Method
Constructor

### Signature
public PermittedUrlsChecker(List<String> allowlist, List<String> denylist)

### Parameters
- **allowlist** (List<String>) - Optional - List of allowed host patterns (host[:port] globs).
- **denylist** (List<String>) - Optional - List of denied host patterns.

### Response
Returns a new PermittedUrlsChecker instance.
```

--------------------------------

### SwaggerParseResult error handling example

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/core-models.md

Parses a location and checks for errors. If getOpenAPI() is null, prints messages to stderr and returns. Otherwise, prints the OpenAPI spec version.

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

SwaggerParseResult result = new OpenAPIV3Parser().readLocation("bad.yaml", null, null);

if (result.getOpenAPI() == null) {
    result.getMessages().forEach(System.err::println); // e.g. "Unable to read location `bad.yaml`"
    return;
}
boolean is31 = result.isOpenapi31();
System.out.println(result.getOpenAPI().getSpecVersion());
```

--------------------------------

### ClasspathHelper.loadFileFromClasspath(String location)

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-refs.md

Loads a resource from the classpath as a string, trying multiple classloader mechanisms. Throws RuntimeException if the resource cannot be read or found.

```APIDOC
## ClasspathHelper.loadFileFromClasspath(String location)

### Description
Loads a resource as a string, trying in order: ClasspathHelper.class.getResourceAsStream, the classloader's getResourceAsStream, then ClassLoader.getSystemResourceAsStream. Separators are unix-ified via FilenameUtils.separatorsToUnix.

### Method
static

### Signature
public static String loadFileFromClasspath(String location)

### Parameters
- **location** (String) - Required - The classpath location of the resource to load.

### Returns
- **String** - The content of the resource as a string.

### Exceptions
- **RuntimeException** - Thrown with message "Could not read <file> from the classpath" on I/O errors, or "Could not find <file> on the classpath" when the resource is not found.
```

--------------------------------

### Mapper Management

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-deserialization.md

Static methods to get and set the YAML mappers used for deserialization. The yaml30Mapper defaults to io.swagger.v3.core.util.Yaml.mapper() and yaml31Mapper to io.swagger.v3.core.util.Yaml31.mapper(). Setters rebuild them via ObjectMapperFactory.createYaml/createYaml31.

```APIDOC
## Mapper Management

### Description
Static methods to get and set the YAML mappers used for deserialization. The yaml30Mapper defaults to io.swagger.v3.core.util.Yaml.mapper() and yaml31Mapper to io.swagger.v3.core.util.Yaml31.mapper(). Setters rebuild them via ObjectMapperFactory.createYaml/createYaml31.

### Methods
- **getOptions()** - Returns the current ParseOptions.
- **setYaml30Mapper(YAMLFactory yamlFactory)** - Sets the YAML 3.0 mapper using the provided YAMLFactory.
- **getYaml30Mapper()** - Returns the current YAML 3.0 ObjectMapper.
- **setYaml31Mapper(YAMLFactory yamlFactory)** - Sets the YAML 3.1 mapper using the provided YAMLFactory.
- **getYaml31Mapper()** - Returns the current YAML 3.1 ObjectMapper.

### Source
DeserializationUtils.java:110-134
```

--------------------------------

### Registering and Removing a Custom Dereferencer

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/reference-dereferencing.md

Demonstrates how to obtain the factory instance, register a custom dereferencer, and handle the unmodifiable nature of the dereferencer list when removing items.

```java
import io.swagger.v3.parser.reference.DereferencersFactory;
import io.swagger.v3.parser.reference.OpenAPIDereferencer;

DereferencersFactory factory = DereferencersFactory.getInstance();

// register a custom dereferencer that runs before OpenAPIDereferencer31
factory.addDereferencer(new OpenAPIDereferencer() {
    @Override public boolean canDereference(DereferencerContext context) { return false; }
    @Override public void dereference(DereferencerContext context, java.util.Iterator<OpenAPIDereferencer> chain) { }
    @Override public Traverser buildTraverser(DereferencerContext context) { return null; }
    @Override public Visitor buildReferenceVisitor(DereferencerContext context, Reference reference, Traverser traverser) { return null; }
});

try {
    factory.removeDereferencer(customDereferencer);
} catch (UnsupportedOperationException e) {
    // getDereferencers() is unmodifiable; iterate a copy when removing
}
```

--------------------------------

### keyName(String keyName)

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/core-models.md

Fluent setter for the header/query parameter name, allowing chaining.

```APIDOC
## keyName(String keyName)

### Description
Fluent setter for the header/query parameter name, allowing chaining.

### Method
Setter

### Signature
public AuthorizationValue keyName(String keyName)

### Parameters
- **keyName** (String) - Required - Header/query parameter name.

### Returns
The current AuthorizationValue instance for chaining.
```

--------------------------------

### getEncoding() and setEncoding(String encoding) static methods

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/OpenAPIV3Parser.md

Static methods to get and set the HTTP/file-read encoding. Default is UTF-8. setEncoding throws EncodingNotSupportedException if the encoding is not supported.

```java
public static String getEncoding()
public static void setEncoding(String encoding)
```

--------------------------------

### join

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/processors.md

Static utility method that joins a source location and a fragment into a full reference string.

```APIDOC
## join

### Description
Static utility method that joins a source location and a fragment into a full reference string.

### Method
join

### Signature
`public static String join(String source, String fragment)`

### Parameters
- **source** (String) - Required - The source location (e.g., a file path).
- **fragment** (String) - Required - The fragment part (e.g., "#/components/schemas/Pet").

### Returns
- **String** - The joined reference string.

### Example
```java
String ref = ExternalRefProcessor.join("./models.yaml", "#/components/schemas/Pet");
```
```

--------------------------------

### Tree Deserialization

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/util-deserialization.md

Static methods to deserialize a string into a JsonNode tree. The method checks if the content is JSON (starts with '{') and uses the appropriate mapper; otherwise it reads as YAML. On IOException, a RuntimeException is thrown.

```APIDOC
## Tree Deserialization

### Description
Static methods to deserialize a string into a JsonNode tree. The method checks if the content is JSON (starts with '{') and uses the appropriate mapper; otherwise it reads as YAML. On IOException, a RuntimeException is thrown.

### Methods
- **deserializeIntoTree(String contents, String fileOrHost)** - Deserializes the given contents into a JsonNode tree.
- **deserializeIntoTree(String contents, String uri, ParseOptions parseOptions, SwaggerParseResult deserializationUtilsResult)** - Deserializes with additional parse options and result collector.

### Behavior
- If `isJson(contents)` is true, uses `ObjectMapperFactory.createJson().readTree(contents)`; otherwise uses `readYamlTree`.
- On IOException, throws `RuntimeException("An exception was thrown while trying to deserialize the contents of " + uri + " into a JsonNode tree", e)`.

### Source
DeserializationUtils.java:160-178
```

--------------------------------

### Rename/reference bookkeeping methods

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/ResolverCache.md

Methods for tracking and managing renamed references during resolution, including checking if a key has been referenced, adding referenced keys, getting and putting renamed refs, and comparing refs for equivalence.

```APIDOC
## Rename/reference bookkeeping methods

### Description
Methods for tracking and managing renamed references during resolution, including checking if a key has been referenced, adding referenced keys, getting and putting renamed refs, and comparing refs for equivalence.

### Methods
- **hasReferencedKey(String modelKey)** - Returns boolean - Checks if the given model key has been referenced during resolution.
- **addReferencedKey(String modelKey)** - Adds a model key to the set of referenced keys.
- **getRenamedRef(String originalRef)** - Returns String - Returns the renamed ref for the given original ref, or null if not renamed.
- **putRenamedRef(String originalRef, String newRef)** - Records a renamed ref mapping from original to new.
- **refsAreEquivalent(String first, String second)** - Returns boolean - Compares two refs after URI normalization/canonicalization to determine equivalence.

### Usage
These methods are used by ExternalRefProcessor and ComponentNameAllocator for collision-safe name allocation. putRenamedRef records the renamed (collision-suffixed) ref, getRenamedRef returns it, refsAreEquivalent compares two refs, and addReferencedKey/hasReferencedKey track which component keys were added during resolution.
```

--------------------------------

### Set YAML depth and TLS trustAll via -D system properties

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/configuration.md

Use this bash command to launch a Java application with Swagger Parser system properties. It sets maxYamlDepth to 10000 and enables trustAll for TLS certificates and hostnames. The -D flags are passed to the JVM before the -jar argument.

```bash
java -DmaxYamlDepth=10000 -Dio.swagger.v3.parser.RemoteUrl.trustAll=true -jar my-app.jar
```

--------------------------------

### PermittedUrlsChecker()

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/safe-url-resolver.md

Creates a PermittedUrlsChecker with empty allowlist and denylist.

```APIDOC
## PermittedUrlsChecker()

### Description
Creates a PermittedUrlsChecker with empty allowlist and denylist (Collections.emptyList()).

### Method
Constructor

### Signature
public PermittedUrlsChecker()

### Parameters
None

### Response
Returns a new PermittedUrlsChecker instance.
```

--------------------------------

### AuthorizationValue(String keyName, String value, String type)

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/core-models.md

Constructor that initializes an AuthorizationValue with the specified key name, value, and type, using a default URL matcher that matches all URLs.

```APIDOC
## AuthorizationValue(String keyName, String value, String type)

### Description
Constructor that initializes an AuthorizationValue with the specified key name, value, and type, using a default URL matcher that matches all URLs.

### Method
Constructor

### Signature
public AuthorizationValue(String keyName, String value, String type)

### Parameters
- **keyName** (String) - Required - Header/query parameter name.
- **value** (String) - Required - Credential value.
- **type** (String) - Required - Where the value goes: "header" or "query" (consumed by RemoteUrl; other values are ignored).

### Returns
A new AuthorizationValue instance with the specified fields set and urlMatcher set to url -> true.
```

--------------------------------

### getKeyName() / setKeyName(String keyName)

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/core-models.md

Plain accessor for the header/query parameter name.

```APIDOC
## getKeyName() / setKeyName(String keyName)

### Description
Plain accessor for the header/query parameter name.

### Method
Getter/Setter

### Signature
public String getKeyName()
public void setKeyName(String keyName)

### Parameters (setter)
- **keyName** (String) - Required - Header/query parameter name.

### Returns (getter)
The header/query parameter name as a String.
```

--------------------------------

### AbstractVisitor

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/reference-traverser.md

AbstractVisitor is a default implementation of the Visitor interface, returning null for every visit* method. Users can override specific methods to customize traversal behavior, such as patching $ref values.

```APIDOC
## AbstractVisitor

### Description
AbstractVisitor is a default implementation of the Visitor interface, returning null for every visit* method. Override only the methods you need to customize traversal behavior.

### Methods
- `visitSchema(Schema schema, List<String> inheritedIds)` - Override to process a Schema node. Returns the modified Schema or null.
- (Other visit* methods inherited from Visitor, defaulting to null)

### Example
java
import io.swagger.v3.parser.reference.AbstractVisitor;
import io.swagger.v3.oas.models.media.Schema;
import java.util.List;

AbstractVisitor a = new AbstractVisitor() {
    @Override public Schema visitSchema(Schema schema, List<String> inheritedIds) {
        if (schema.get$ref() != null && schema.get$ref().startsWith("http")) {
            schema.set$ref("#/components/schemas/" + refName(schema.get$ref()));
        }
        return schema;
    }
};

```

--------------------------------

### Minimal ref-patching visitor using AbstractVisitor

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/reference-traverser.md

Override only the visitSchema method to patch external HTTP references to local component references. The AbstractVisitor default implementation returns null for every visit* method, so only the overridden method needs to be implemented. The refName method is not defined in the snippet and must be provided by the user.

```java
import io.swagger.v3.parser.reference.AbstractVisitor;
import io.swagger.v3.oas.models.media.Schema;
import java.util.List;

AbstractVisitor a = new AbstractVisitor() {
    @Override public Schema visitSchema(Schema schema, List<String> inheritedIds) {
        if (schema.get$ref() != null && schema.get$ref().startsWith("http")) {
            schema.set$ref("#/components/schemas/" + refName(schema.get$ref()));
        }
        return schema;
    }
};
```

--------------------------------

### read(String location, List<AuthorizationValue> auths, ParseOptions resolve)

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/OpenAPIV3Parser.md

Iterates all getExtensions(), calls readLocation on each, logs messages, and returns the first non-null OpenAPI. Returns null if location is null or no extension succeeded.

```APIDOC
## read(String location, List<AuthorizationValue> auths, ParseOptions resolve)

### Description
Iterates all `getExtensions()`, calls `readLocation` on each, logs messages, and returns the first non-null `OpenAPI`. Returns `null` if `location` is `null` or no extension succeeded.

### Method
read

### Signature
`public OpenAPI read(String location, List<AuthorizationValue> auths, ParseOptions resolve)`

### Parameters
- **location** (String) - Required - The location of the OpenAPI definition.
- **auths** (List<AuthorizationValue>) - Optional - Authorization values for the request.
- **resolve** (ParseOptions) - Optional - Parse options, e.g., setResolveFully(true) for dereferencing.

### Returns
- **OpenAPI** - The parsed OpenAPI object, or null if parsing failed.

### Example
```java
ParseOptions options = new ParseOptions();
options.setResolveFully(true);
OpenAPI dereferenced = new OpenAPIV3Parser().read("a.yaml", null, options);
```
```

--------------------------------

### Deserialize with path and options

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/OpenAPIDeserializer.md

Delegates to the full deserialization method. Note that the provided ParseOptions instance is ignored in favor of a fresh instance.

```java
public SwaggerParseResult deserialize(JsonNode rootNode, String path, ParseOptions options)
{
	Delegates to deserialize(rootNode, path, new ParseOptions(), false) — note the ParseOptions argument is ignored here (a fresh instance is used); use the 4-argument overload to pass options through.
}
```

--------------------------------

### process(Swagger swagger) method signature

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/SwaggerInventory.md

Entry point that processes the top-level Swagger object. Returns SwaggerInventory for fluent chaining.

```java
public SwaggerInventory process(Swagger swagger)
```

--------------------------------

### Parse local file, resolve refs, write YAML

Source: https://github.com/swagger-api/swagger-parser/blob/master/_autodocs/api-reference/cli.md

Command-line invocation to parse a local OpenAPI file, resolve references, and write the result as YAML to an output file.

```bash
java -cp swagger-parser-cli.jar io.swagger.v3.parser.SwaggerParser \
  -i ./openapi.yaml -resolve -o ./resolved.yaml
```
Tokens:
Raw