将 XSD 导入 OpenAPI [英] Import XSD to OpenAPI

问题描述

我在 XSD 文件中有一些模型定义，我需要从 OpenApi 定义中引用这些模型.由于文件太大，无法手动重构，我需要将其放入构建系统，以便在更改 XSD 时，我可以为 OpenApi 重新生成模型/架构.

I have some model definition inside a XSD file and I need to reference these models from an OpenApi definition. Manually remodeling is no option since the file is too large, and I need to put it into a build system, so that if the XSD is changed, I can regenerate the models/schemas for OpenApi.

我尝试过的和几乎有效的方法是使用 xsd2json 然后用节点模块转换它 json-schema-to-openapi.但是 xsd2json 正在删除一些 complexElement 模型.例如 "$ref": "#/definitions/tns:ContentNode" 在一个模型内部用作子类型，但模式中没有 ContentNode 的定义，当我查看 XSD 时，ContentNode 有一个 complexElement 定义.

What I tried and what nearly worked is using xsd2json and then converting it with the node module json-schema-to-openapi. However xsd2json is dropping some of the complexElement models. For example "$ref": "#/definitions/tns:ContentNode" is used inside of one model as the child type but there is no definition for ContentNode in the schema, where when I look into the XSD, there is a complexElement definition for ContentNode.

另一种我还没有尝试过但对我来说似乎有点过分的方法是使用 xjb 从 XSD 生成 Java 模型，然后使用 JacksonSchema 生成 json 模式.

Another approach which I haven't tried yet but seems a bit excessive to me is using xjb to generate Java models from the XSD and then using JacksonSchema to generate the json schema.

是否有任何既定的库或方法可以在 OpenApi 中使用 XSD?

Is there any established library or way, to use XSD in OpenApi?

推荐答案

我最终实现了第二种方法，使用 jaxb 将 XSD 转换为 Java 模型，然后使用 Jackson 将模式写入文件.

I ended up implementing the second approach using jaxb to convert the XSD to java models and then using Jackson to write the schemas to files.

摇篮:

plugins {
    id 'java'
    id 'application'
}

group 'foo'
version '1.0-SNAPSHOT'

sourceCompatibility = 1.8

repositories {
    mavenCentral()
}

dependencies {
    testCompile group: 'junit', name: 'junit', version: '4.12'
    compile group: 'com.fasterxml.jackson.module', name: 'jackson-module-jsonSchema', version: '2.9.8'
}

configurations {
    jaxb
}

dependencies {
    jaxb (
            'com.sun.xml.bind:jaxb-xjc:2.2.7',
            'com.sun.xml.bind:jaxb-impl:2.2.7'
    )
}

application {
    mainClassName = 'foo.bar.Main'
}

task runConverter(type: JavaExec, group: 'application') {
    classpath = sourceSets.main.runtimeClasspath

    main = 'foo.bar.Main'
}

task jaxb {
    System.setProperty('javax.xml.accessExternalSchema', 'all')
    def jaxbTargetDir = file("src/main/java")

    doLast {
        jaxbTargetDir.mkdirs()

        ant.taskdef(
                name: 'xjc',
                classname: 'com.sun.tools.xjc.XJCTask',
                classpath: configurations.jaxb.asPath
        )
        ant.jaxbTargetDir = jaxbTargetDir

        ant.xjc(
                destdir: '${jaxbTargetDir}',
                package: 'foo.bar.model',
                schema: 'src/main/resources/crs.xsd'
        )
    }
}

compileJava.dependsOn jaxb

使用转换器主类，可以执行以下操作:

With a converter main class, that does something along the lines of:

package foo.bar;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.module.jsonSchema.JsonSchema;
import com.fasterxml.jackson.module.jsonSchema.JsonSchemaGenerator;
import foo.bar.model.Documents;

public class Main {

    public static void main(String[] args) {
        ObjectMapper mapper = new ObjectMapper();
        JsonSchemaGenerator schemaGen = new JsonSchemaGenerator(mapper);
        try {
            JsonSchema schema = schemaGen.generateSchema(Documents.class);
            System.out.print(mapper.writerWithDefaultPrettyPrinter().writeValueAsString(schema));
        } catch (JsonMappingException e) {
            e.printStackTrace();
        } catch (JsonProcessingException e) {
            e.printStackTrace();
        }
    }

}

虽然它仍然不完美，...这需要迭代所有模型类并生成一个带有模式的文件.此外，它不使用引用，如果一个类有另一个类的成员，则模式将内联打印而不是引用.这需要使用 SchemaFactoryWrapper 进行更多自定义，但可以做到.

It is still not perfect though,... this would need to iterate over all the model classes and generate a file with the schema. Also it doesn't use references, if a class has a member of another class, the schema is printed inline instead of referencing. This requires a bit more customization with the SchemaFactoryWrapper but can be done.

这篇关于将 XSD 导入 OpenAPI的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！