생성 된 클래스를 만드는 방법 XML 스키마 문서의 Javadoc이 포함되어 있습니다.
문제
현재 XML 스키마로 작업하고 있습니다 <xsd:annotation>
/<xsd:documentation>
대부분의 유형과 요소에서. 이 XML 스키마에서 Java Bean을 생성 할 때 해당 Bean의 Javadoc에는 유형/요소의 허용 된 내용에 대한 일반적인 생성 정보 만 포함되어 있습니다.
나는 내용을보고 싶다 <xsd:documentation>
관련 장소에서 태그 (예 : ComplexTType에 대한 해당 태그의 내용은 해당 복합 유형을 나타내도록 생성 된 클래스의 Javadoc에 표시되어야합니다).
이것을 달성 할 방법이 있습니까?
편집하다:이 XML 스키마는 JAX-WS와 함께 WSDL에서 사용 되므로이 태그도 적절할 수 있습니다.
편집 2: 나는 읽었다 <jxb:javadoc>
. 내가 이해 한 바에 따르면 별도의 JAXB 바인딩 파일 또는 XML 스키마에서 직접 지정할 수 있습니다. 그것은 내 문제를 거의 해결할 것입니다. 그러나 기존을 사용하고 싶습니다 <xsd:documentation>
태그는 Javadoc이 문서의 주요 대상이 아니기 때문에 (주로 데이터 구조에 대한 정보는 주로 생성 된 Java Bean에 대한 정보)가 아니기 때문에 비 JAXB 도구도 정보에 액세스 할 수 있도록 허용합니다. 둘 다 문서 제공 <jxb:javadoc>
그리고 xsd:documentation>
"느낌"잘못된 이유는 없습니다.
편집 3: Pascal의 답변 덕분에 나는 이미 절반의 해결책이 있다는 것을 깨달았습니다. <xsd:documentation>
의 complexType
S는 Javadoc의 시작 부분에 작성되었습니다! 문제는 여전히 그 것입니다 뿐 저것 complexType
S가 사용됩니다 simpleType
S (클래스를 초래할 수 있음)와 요소는 여전히 Javadoc-ness입니다.
해결책
나는 정기적으로 얻을 수 없었습니다 xsd:documentation
Java 소스를 제외하고 배치해야합니다 경우에만 복잡한 유형이었습니다. 요소, 간단한 유형 등에 대한 문서는 무시됩니다.
그래서 나는 결국 사용하게된다 jxb:javadoc
. 그렇게하려면 정의를 포함하십시오 xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
당신의 <xsd:schema>
요소.
아이를 추가하십시오 <xsd:complexType>
또는 <xsd: element>
또는 <xsd:attribute>
:
<xsd:annotation><xsd:appinfo><jxb:XXX><jxb:javadoc>
This is my comment for a class/property
</jxb:javadoc></jxb:XXX></xsd:appinfo></xsd:annotation>
여기서 XXX는 "클래스"또는 "속성"입니다.
패키지의 경우 아이를 씁니다 xsd:schema
<xsd:annotation><xsd:appinfo><jxb:schemaBindings><jxb:package name="com.acme"><jxb:javadoc>
This is my comment for a package
</jxb:javadoc></jxb:package></jxb:schemaBindings></xsd:appinfo></xsd:annotation>
HTML 문서를 작성하려면 브래킷이 필요합니다 <![CDATA[ --- ]]>
(편집 : 내 답을 작성하는 동안 질문은 OP에 의해 편집되었으므로 그에 따라 업데이트하고 있습니다)
제 경우에는 Javadoc이 유일한 대상 이었으므로 사용하는 것이 허용되었습니다. jxb:javadoc
. 그러나 귀하의 업데이트는 완벽하게 이해되며 실제로는 전적으로 귀하에게 동의합니다. 슬프게도, 나는 당신이 설명하는 상황에 대한 이상적인 해결책을 찾지 못했습니다 (따라서이 질문을 매우 신중하게 따를 것입니다). 어쩌면 당신은 같은 것을 사용할 수 있습니다 xframe 문서를 생성합니다 xsd:documentation
, 그러나 이것은 질문에 대답하지 않습니다.
다른 팁
JAXB 참조 구현에서는 불가능합니다. XJC 플러그인을 작성하려고하더라도 플러그인 API에 스키마 정의에 대한 참조가 제공되지 않으므로이 정보를 추출 할 방법이 없습니다.
우리의 유일한 희망은 JAXB의 미래 버전이 상황을 해결하기를 희망합니다. 있습니다 여기에서 기능 요청을 열어줍니다.
다음 기술이 Java Element 클래스 (XML Schemas에서 생성)에 Javadoc 헤더를 추가하는 데 효과적입니다. XML 스키마 주석 및 AppInfo 태그에 중첩 된 JAX-B 네임 스페이스에 정의 된 태그로 Javadoc을 중첩합니다. JAXB 네임 스페이스는 문서화 태그 유형을 정의합니다. 나는 두 가지를 사용합니다 : 클래스와 속성 태그. 다음 네임 스페이스에 정의 됨 : xmlns : jxb = "http://java.sun.com/xml/ns/jaxb"
1) 클래스를 문서화하려면 다음 순서로 JAXB "클래스"태그를 사용합니다.
<xs:complexType name="Structure">
<xs:annotation>
<xs:appinfo>
<jxb:class>
<jxb:javadoc>
Documentation text goes here. Since parsing the schema
into Java involves evaluating the xml, I escape all
the tags I use as follows <p> for <p>.
</jxb:javadoc>
</jxb:class>
</xs:appinfo>
</xs:annotation>
.
.
.
</xs:complexType>
2) 요소를 문서화하려면 다음과 같이 "속성"태그를 사용합니다.
<xs:element name="description" type="rep:NamedString">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
</xs:element>
3) 동일한 태그 세트를 사용하여 속성을 문서화합니다.
<xs:attribute name="name" type="xs:NCName" use="required">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
4) 선택을 문서화하기 위해 재산 JAXB 태그를 사용하고 선택을 문서화합니다.
<xs:choice maxOccurs="unbounded">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
<xs:element name="value" type="rep:NamedValue" />
<xs:element name="list" type="rep:NamedList" />
<xs:element name="structure" type="rep:NamedStructure" />
</xs:choice>
이 태그가없는 목록을 생성하기 때문에 여기에 개별 선택을 문서화하려고 시도하는 것은 실패 할 것입니다.
특히이 경우 XJC 플러그인을 썼습니다 XJC 문서화 주석-플루인.
그것이하는 일 : <annotation><documentation>
-> Java 클래스 주석
이 객체가 설명되어 있다고 말했습니다 XSD
:
<xs:complexType name="CadastralBlock">
<xs:annotation>
<xs:documentation>Cadastral quarter</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="number" type="xs:string">
<xs:annotation>
<xs:documentation>Cadastral number</xs:documentation>
</xs:annotation>
</xs:element>
</xs:complexType>
우리는 xjc like를 실행합니다.
xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated scheme.xsd
그리고 클래스와 같은 클래스 (단순성을 위해 Getters, Setters 및 모든 주석이 생략 됨) : :
public class CadastralBlock {
protected String number;
}
그러나 제 경우에는 클래스와 필드가 소스 파일로 명명 된 방법을 알고 싶어합니다! 그래서이 플러그인이하는 일!
그래서 당신은 얻는다 :
@XsdInfo(name = "Cadastral quarter", xsdElementPart = "<complexType name=\"CadastralBlock\">\n <complexContent>\n <restriction base=\"{http://www.w3.org/2001/XMLSchema}anyType\">\n <sequence>\n <element name=\"number\" type=\"{http://www.w3.org/2001/XMLSchema}string\"/></sequence>\n </restriction>\n </complexContent></complexType>")
public class CadastralBlock {
@XsdInfo(name = "Cadastral number")
protected String number;
}
사용하는 방법
CommandLine에서 수동 호출
실행을 원하는 경우 수동으로 플러그인을 사용하여 jar 클래스를 실행하고 옵션을 추가하십시오. -XPluginDescriptionAnnotation
. Fe :
xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated -XPluginDescriptionAnnotation scheme.xsd
Java/Groovy에서 전화하십시오
Driver.run(
[
'-XPluginDescriptionAnnotation'
,'-d', generatedClassesDir.absolutePath
,'-p', 'info.hubbitus.generated.test'
,'CadastralBlock.xsd'
] as String[]
,new XJCListener() {...}
)
예를 들어 xjcplugindescriptionannotationtest 테스트를 참조하십시오.
Gradle에서 사용하십시오
와 함께 Gradle-xJC-Plugin:
plugins {
id 'java'
id 'org.unbroken-dome.xjc' version '1.4.1' // https://github.com/unbroken-dome/gradle-xjc-plugin
}
...
dependencies {
xjcClasspath 'info.hubbitus:xjc-documentation-annotation-plugin:1.0'
}
// Results by default in `build/xjc/generated-sources`
xjcGenerate {
source = fileTree('src/main/resources') { include '*.xsd' }
packageLevelAnnotations = false
targetPackage = 'info.hubbitus.xjc.plugin.example'
extraArgs = [ '-XPluginDescriptionAnnotation' ]
}
완벽한 gradle
예제 예제 프로젝트 -gradle 프로젝트 디렉토리.