Swagger YAML中$ref映射：是否存在可解析$ref的YAML转Java Map工具？

Great question! Let's break this down clearly, covering both how $ref works in Swagger YAML and the tools you can use to parse it into a Java Map with full reference resolution.

$ref is Swagger's implementation of JSON Reference, built to eliminate duplicate schema definitions by referencing reusable components (usually in the definitions section for Swagger 2.0, or components/schemas for OpenAPI 3.x). Here's how it operates:

• Internal References: To point to a definition within the same YAML file, use a fragment identifier starting with #. For example:

  paths:
    /users/{id}:
      get:
        responses:
          200:
            schema:
              $ref: '#/definitions/User' # References the User schema in the same file
  
  definitions:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
  

• External Local References: To reference a definition in another local file, use a relative path plus the fragment:

  $ref: './common-schemas.yaml#/Address'
  

• External Remote References: You can also reference schemas from remote URLs:

  $ref: 'https://api.example.com/swagger/schemas.yaml#/Product'
  

• Key Gotcha: $ref is a replacement—when resolved, the entire $ref node is replaced with the referenced content. You can't have other properties (like description) alongside a $ref in the same node; this will cause parsing errors.

There are a few reliable tools that handle $ref resolution and can convert your Swagger YAML into a Java Map:

1. Official Swagger/OpenAPI Parser (io.swagger.parser.v3) #

This is the go-to library for parsing Swagger 2.0 and OpenAPI 3.x documents. It automatically resolves all internal and external $refs, and you can convert the parsed OpenAPI object to a Map using Jackson.

Here's a quick code example:

import io.swagger.v3.parser.OpenAPIV3Parser;
import io.swagger.v3.oas.models.OpenAPI;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;

public class SwaggerToMapConverter {
    public static void main(String[] args) throws Exception {
        // Parse the YAML file, resolving all references automatically
        OpenAPI openApiDoc = new OpenAPIV3Parser().read("path/to/your/swagger.yaml");
        
        // Convert the parsed OpenAPI object to a Java Map
        ObjectMapper objectMapper = new ObjectMapper();
        Map<String, Object> swaggerMap = objectMapper.convertValue(openApiDoc, Map.class);
        
        // The map now contains fully resolved schemas—no $ref entries remain
    }
}

For Swagger 2.0, use the SwaggerParser class from io.swagger.parser.v2 instead.

2. Jackson with JSON Reference Module #

If you prefer a more generic approach without Swagger-specific libraries, you can use Jackson's jackson-module-json-reference to parse the YAML and resolve $refs directly into a Map.

Example code:

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
import com.fasterxml.jackson.module.json.JsonReferenceModule;
import java.io.File;
import java.util.Map;

public class YamlRefResolver {
    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper(new YAMLFactory());
        // Register the module to handle $ref resolution
        mapper.registerModule(new JsonReferenceModule());
        
        // Parse the YAML into a Map with all references resolved
        Map<String, Object> resolvedMap = mapper.readValue(new File("path/to/swagger.yaml"), Map.class);
    }
}

Note: You'll need to ensure all referenced local files are accessible via the correct relative paths, and remote references may require additional configuration for network access.

Key Notes #

• Always match your parser version to your Swagger/OpenAPI version (v2 for Swagger 2.0, v3 for OpenAPI 3.x) to avoid compatibility issues.
• For large documents with many external references, check the parser's configuration options to control how references are loaded (e.g., caching remote schemas).

内容的提问来源于stack exchange，提问作者letthefireflieslive