[
https://issues.apache.org/jira/browse/CAMEL-7999?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-7999:
-------------------------------
Description:
A Camel release contains many components, and we have the ability to let
components document which options they offer.
Though there is currently a few shortcomings that can be improved
- the component json schema is currently runtime generated, which requires to
load the component and create an instance of it. Instead we should build-time
generate it, which we do today with the camel apt compiler plugin. *DONE*
- we should include documentation about the option from the javadoc, that
allows end users to fully document a component using plain java getter/settr
with javadocs, and add those @UriParam annotations for the apt compiler to
detect and leverage *DONE*
- add a module that embeds all these json schema files in a single module, and
also other information, such as the xml schemas, and what else can be handy.
Then there is a single module as a one stop shop for tooling and whatnot to
gather information about a Camel release.
- allow at runtime to explain an endpoint uri what the options in use are, eg
as we got the json schema, we can add mbeans that can explain those options,
than we can use in tooling, JMX, karaf commands etc. And also IDE editors etc
*DONE*
- enrich the dsl xml to inject javadoc for the eips into the xml schema, so we
have documented in the xsd directly that any tooling can use. We have a old
ticket about this. But the apt compiler plugin can detect the @JAXB annotations
in the model and extract the javadoc, and generate a json schema with, and then
we can load those and enrich into the generated xsd, or enrich into the jaxb
model generator, or something.
- migrate more Camel components to include javadoc as documentation for their
options
- figure out how to specify a default value in the json schema. Unfortunately
the apt plugin cannot grab that from the source code. So the only solution I
can think of now is to add an attribute to the @UriParam where you can specify
that, eg this is also what I have seen others do. There is now a defaultValue
attribute on UriParam to be used. *DONE*
- add component summary to component json file so we have a description of what
the component does *DONE*
- add attribute to @UriEndpoint to link it to the component class, so we can
include the class name of the component in the json schema, which allows Camel
to link from component class -> schema. eg the point is that if people define a
component as "activemq" we do not know its the jms schema that has its
documentation. Though we can infer this by the component class name. And
alternative is for a component to have an api to return its original schema
name etc. So activemq can say "jms" etc. We can resolve this by iterating the
component data, and find the FQN of the components. *DONE*
- add @UriComponent annotation to component class which allows end users to
provide meta-data about the component. Currently we grab a summary of what the
component does from the maven pom.xml. Though this annotation prepares us for
being able to scan the component class as well for which option it provides, so
we can have out of the box documentation for that also.
- add JMX/Java API to explain a component and also get a tabular data with a
list of all components and that data. *DONE*
- improve karaf commands to use the component information to show that also
*DONE*
- add name of karaf feature of the component, eg its 99% came-xxx, but there
may be some exceptions. We can likely add a property to the maven plugin that
generates component.properties to include the karaf feature name as the
artifactId by default. But allow to set a property in the pom.xml in case there
is another name, or no karaf feature
- add support for @UriPath in apt plugin *DONE*
was:
A Camel release contains many components, and we have the ability to let
components document which options they offer.
Though there is currently a few shortcomings that can be improved
- the component json schema is currently runtime generated, which requires to
load the component and create an instance of it. Instead we should build-time
generate it, which we do today with the camel apt compiler plugin. *DONE*
- we should include documentation about the option from the javadoc, that
allows end users to fully document a component using plain java getter/settr
with javadocs, and add those @UriParam annotations for the apt compiler to
detect and leverage *DONE*
- add a module that embeds all these json schema files in a single module, and
also other information, such as the xml schemas, and what else can be handy.
Then there is a single module as a one stop shop for tooling and whatnot to
gather information about a Camel release.
- allow at runtime to explain an endpoint uri what the options in use are, eg
as we got the json schema, we can add mbeans that can explain those options,
than we can use in tooling, JMX, karaf commands etc. And also IDE editors etc
*DONE*
- enrich the dsl xml to inject javadoc for the eips into the xml schema, so we
have documented in the xsd directly that any tooling can use. We have a old
ticket about this. But the apt compiler plugin can detect the @JAXB annotations
in the model and extract the javadoc, and generate a json schema with, and then
we can load those and enrich into the generated xsd, or enrich into the jaxb
model generator, or something.
- migrate more Camel components to include javadoc as documentation for their
options
- figure out how to specify a default value in the json schema. Unfortunately
the apt plugin cannot grab that from the source code. So the only solution I
can think of now is to add an attribute to the @UriParam where you can specify
that, eg this is also what I have seen others do. There is now a defaultValue
attribute on UriParam to be used. *DONE*
- add component summary to component json file so we have a description of what
the component does *DONE*
- add attribute to @UriEndpoint to link it to the component class, so we can
include the class name of the component in the json schema, which allows Camel
to link from component class -> schema. eg the point is that if people define a
component as "activemq" we do not know its the jms schema that has its
documentation. Though we can infer this by the component class name. And
alternative is for a component to have an api to return its original schema
name etc. So activemq can say "jms" etc. We can resolve this by iterating the
component data, and find the FQN of the components. *DONE*
- add @UriComponent annotation to component class which allows end users to
provide meta-data about the component. Currently we grab a summary of what the
component does from the maven pom.xml. Though this annotation prepares us for
being able to scan the component class as well for which option it provides, so
we can have out of the box documentation for that also.
- add JMX/Java API to explain a component and also get a tabular data with a
list of all components and that data. *DONE*
- improve karaf commands to use the component information to show that also
*DONE*
- add name of karaf feature of the component, eg its 99% came-xxx, but there
may be some exceptions. We can likely add a property to the maven plugin that
generates component.properties to include the karaf feature name as the
artifactId by default. But allow to set a property in the pom.xml in case there
is another name, or no karaf feature
- add support for @UriPath in apt plugin
> Camel Toolbox - Easy information about all Camel components and the release
> for tooling
> ---------------------------------------------------------------------------------------
>
> Key: CAMEL-7999
> URL: https://issues.apache.org/jira/browse/CAMEL-7999
> Project: Camel
> Issue Type: New Feature
> Components: camel-core, jmx, tooling
> Reporter: Claus Ibsen
> Assignee: Claus Ibsen
> Fix For: 2.15.0
>
>
> A Camel release contains many components, and we have the ability to let
> components document which options they offer.
> Though there is currently a few shortcomings that can be improved
> - the component json schema is currently runtime generated, which requires to
> load the component and create an instance of it. Instead we should build-time
> generate it, which we do today with the camel apt compiler plugin. *DONE*
> - we should include documentation about the option from the javadoc, that
> allows end users to fully document a component using plain java getter/settr
> with javadocs, and add those @UriParam annotations for the apt compiler to
> detect and leverage *DONE*
> - add a module that embeds all these json schema files in a single module,
> and also other information, such as the xml schemas, and what else can be
> handy. Then there is a single module as a one stop shop for tooling and
> whatnot to gather information about a Camel release.
> - allow at runtime to explain an endpoint uri what the options in use are, eg
> as we got the json schema, we can add mbeans that can explain those options,
> than we can use in tooling, JMX, karaf commands etc. And also IDE editors etc
> *DONE*
> - enrich the dsl xml to inject javadoc for the eips into the xml schema, so
> we have documented in the xsd directly that any tooling can use. We have a
> old ticket about this. But the apt compiler plugin can detect the @JAXB
> annotations in the model and extract the javadoc, and generate a json schema
> with, and then we can load those and enrich into the generated xsd, or enrich
> into the jaxb model generator, or something.
> - migrate more Camel components to include javadoc as documentation for their
> options
> - figure out how to specify a default value in the json schema. Unfortunately
> the apt plugin cannot grab that from the source code. So the only solution I
> can think of now is to add an attribute to the @UriParam where you can
> specify that, eg this is also what I have seen others do. There is now a
> defaultValue attribute on UriParam to be used. *DONE*
> - add component summary to component json file so we have a description of
> what the component does *DONE*
> - add attribute to @UriEndpoint to link it to the component class, so we can
> include the class name of the component in the json schema, which allows
> Camel to link from component class -> schema. eg the point is that if people
> define a component as "activemq" we do not know its the jms schema that has
> its documentation. Though we can infer this by the component class name. And
> alternative is for a component to have an api to return its original schema
> name etc. So activemq can say "jms" etc. We can resolve this by iterating the
> component data, and find the FQN of the components. *DONE*
> - add @UriComponent annotation to component class which allows end users to
> provide meta-data about the component. Currently we grab a summary of what
> the component does from the maven pom.xml. Though this annotation prepares us
> for being able to scan the component class as well for which option it
> provides, so we can have out of the box documentation for that also.
> - add JMX/Java API to explain a component and also get a tabular data with a
> list of all components and that data. *DONE*
> - improve karaf commands to use the component information to show that also
> *DONE*
> - add name of karaf feature of the component, eg its 99% came-xxx, but there
> may be some exceptions. We can likely add a property to the maven plugin that
> generates component.properties to include the karaf feature name as the
> artifactId by default. But allow to set a property in the pom.xml in case
> there is another name, or no karaf feature
> - add support for @UriPath in apt plugin *DONE*
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
