restlet-framework-java
restlet-framework-java copied to clipboard
Introspector documentation needs improvement
The Javadoc page of the Introspector is here: http://restlet.com/technical-resources/restlet-framework/javadocs/2.3/jse/ext/org/restlet/ext/apispark/Introspector.html
This page doesn't contain any information on the parameters supported by the Introspector program. Also, it doesn't include an hyperlink to the dedicated page in the User Guide which is: https://restlet.com/technical-resources/restlet-framework/guide/2.3/extensions/apispark/introspector
Also, here is the output of the built-in help with some modifications suggestions included. You actually have to run the tool with --help parameter to see the details.
SYNOPSIS
org.restlet.ext.apispark.Introspector [credentials] [actions] [options] [--language
swagger SWAGGER_DEFINITION_URL_OR_PATH | APPLICATION]
DESCRIPTION
Publish to the APISpark platform the description of your Web API, represented by
APPLICATION, the full name of your Restlet or JAX-RS application class or by the Swagger
definition available at URL/PATH
If the whole process is successful, it displays the url of the corresponding descriptor or
connector cell.
EXAMPLES
org.restlet.ext.apispark.Introspector -u 1234 -p Xy12 --create-descriptor
com.acme.Application
org.restlet.ext.apispark.Introspector -u 1234 -p Xy12 --new-version --id 60
com.acme.Application
org.restlet.ext.apispark.Introspector -u 1234 -p Xy12 --update --update-strategy replace
--id 60 --version 1 --language swagger http://acme.com/api/swagger
OPTIONS
-h, --help Prints this help.
[credentials]
-u, --username username
The mandatory user name available from the Tokens section of your APISpark Account page.
-p, --password password
The mandatory secret key available from the Tokens section of your APISpark Account page.
[actions]
-d, --create-descriptor
Creates a new API Descriptor in APISpark based on the introspection result.
-c, --create-connector
Creates a new API Connector in APISpark based on the introspection result.
-n, --new-version
Creates a new major version of the APISpark cell identified by the -i (--id) option
-U, --update
Updates the APISpark cell identified specified by the -i (--id) and -v (--version)
options. Uses the default update strategy (update) except if -S (--update-strategy)
option is specified.
[options]
-i, --id cellId
The identifier of an existing APISpark cell (API Descriptor or Connector) that you want
to update. Required if -n (--new-version) or -U (--update) options are specified.
-v, --version cellVersion
The major version of the cell to be updated.
Required if -U (--update) option is specified.
-s, --update-strategy strategy
Specifies the update strategy. Available strategies:
- update: (default) new elements will be added to the APISpark cell,
primitive fields of existing objects will be updated. Nothing will be deleted.
- replace: deletes all the information in the APISpark cell
and fills it again with introspected definition.
--component componentClass
The optional full name of your Restlet Component class. This allows to collect
additional metadata, such as the endpoint.
-l, --language languageName
The optional name of the description language of the definition you want to upload.
Possible value:
- swagger: Swagger 1.2 specification.
--sections
Set section of introspected resources from Java package name.
-v, --verbose
The optional parameter switching the process to a verbose mode
ENHANCE INTROSPECTION
You can extend the basic introspection and enrich the generated documentation by providing
dedicated helpers to the introspector. By default, Swagger annotation are supported.
Introspection use the Java Service Loader system. To add a new helper, create a
'META-INF/services/org.restlet.ext.apispark.internal.introspection.IntrospectionHelper' file
with the name of your implementation class.