FusionDocumentation

Menu

Documentation generation

This page details Documentation generation.

Dependency

<dependency>
  <groupId>io.yupiik.fusion</groupId>
  <artifactId>fusion-documentation</artifactId>
  <version>${fusion.version}</version>
</dependency>

Integration with yupiik-tools-maven-plugin

IMPORTANT

the main way to use these generators in practice is as pre-actions of the yupiik-tools-maven-plugin minisite goal, not as standalone programs. The plugin runs them before rendering the site, letting you embed generated Asciidoc (configuration keys, CLI command reference) directly into your minisite.

Here is the wiring used by this very project (fusion-documentation/pom.xml): each generator is declared as a <preAction>, and the generated partials land in src/main/minisite/content/_partials/generated/ so they can be include::d from the hand-written pages:

<plugin>
  <groupId>io.yupiik.maven</groupId>
  <artifactId>yupiik-tools-maven-plugin</artifactId>
  <version>${yupiik-tools.version}</version>
  <executions>
    <execution>
      <id>minisite</id>
      <goals><goal>minisite</goal></goals>
      <configuration>
        <source>src/main/minisite</source>
        <preActions>
          <preAction>
            <type>io.yupiik.fusion.documentation.ConfigurationDocumentationGenerator</type>
            <parameters>
              <includeEnvironmentNames>true</includeEnvironmentNames>
            </parameters>
          </preAction>
          <preAction>
            <type>io.yupiik.fusion.documentation.CliDocumentationGenerator</type>
          </preAction>
        </preActions>
        <attributes>
          <partialsdir>${project.basedir}/src/main/minisite/content/_partials</partialsdir>
        </attributes>
      </configuration>
    </execution>
  </executions>
  <dependencies>
    <dependency>
      <groupId>io.yupiik.fusion</groupId>
      <artifactId>fusion-documentation</artifactId>
      <version>${fusion.version}</version>
    </dependency>
  </dependencies>
</plugin>

Each generator consumes the metadata the Fusion annotation processor produced at compile time (META-INF/fusion/configuration/documentation.json for configuration, the CLI command metadata for CliDocumentationGenerator) and writes an .adoc partial which you then reference with an include directive from your content page (for example /home/fpa/planets/tatooine/yupiik/fusion/fusion-documentation/src/main/minisite/content/_partials/generated/documentation.my-app.adoc). Since the pre-action runs before the site renders, the partial exists by the time the page is resolved.

TIP

preview the site locally with mvn compile yupiik-tools:serve-minisite -e in the documentation module. The generated partials are committed (see the module rules): rebuild with mvn install -pl fusion-documentation -am so the processor regenerates the metadata before the site renders.

JSON-RPC/OpenRPC to Asciidoc

The class io.yupiik.fusion.documentation.OpenRPC2Adoc enables to convert the partial OpenRPC metadata (META-INF/fusion/jsonrpc/openrpc.json) to Asciidoc format for an easier integration in documentation.

Configuration:

Name Description

input

the location of the input file (json), often it will be target/classes/META-INF/fusion/jsonrpc/openrpc.json.

output

the location of the output file (asciidoc).

JSON-RPC/OpenRPC to OpenAPI

OpenAPI is the OpenRPC for plain old RESTful API. However it has some great tooling - SwaggerUI to not cite it.

The class io.yupiik.fusion.documentation.OpenRPC2OpenAPI enables to convert the partial OpenRPC metadata (META-INF/fusion/jsonrpc/openrpc.json) to OpenAPI format for an easier integration in documentation and in particular SwaggerUI.

Configuration:

Name Description

input

the location of the input file (json), often it will be target/classes/META-INF/fusion/jsonrpc/openrpc.json.

output

the location of the output file (json).

*.url

define a server URL, * is a prefix used to match the description (you can define multiple servers while prefix is unique).

*.description

define a server description, * is a prefix used to match the url.

info.*

define info block of OpenAPI. Ensure to define info.title, info.version and info.description at least.

To integrate it with SwaggerUI you have to register the SwaggerUI requestInterceptor which will convert the request url to the server url (which must be JSON-RPC endpoint) since the converter moves methods as path to comply to OpenAPI model:

SwaggerUIBundle({
  ...,
  requestInterceptor: function (request) {
    if (request.loadSpec) {
      return request;
    }
    var method = request.url.substring(request.url.lastIndexOf('/') + 1);
    return Object.assign(request, {
      url: spec.servers.filter(function (server) { return request.url.indexOf(server.url) === 0; })[0].url,
      body: JSON.stringify({ jsonrpc: '2.0', method: method, params: JSON.parse(request.body) }, undefined, 2)
    });
  },
});

JSON-RPC/OpenRPC to Postman

The class io.yupiik.fusion.documentation.OpenRPC2Postman enables to convert the partial OpenRPC metadata (META-INF/fusion/jsonrpc/openrpc.json) to a Postman collection.

Configuration:

Name Description

input

the location of the input file (json), often it will be target/classes/META-INF/fusion/jsonrpc/openrpc.json.

output

the location of the output file (json).

info.*

define info block of collection. Ensure to define info.title, info.version.

server.url

define a server URL to use.

Format documentation in Asciidoc

io.yupiik.fusion.documentation.ConfigurationDocumentationGenerator enables to format the documentation in asciidoc.

If you use Yupiik tools minisite, configuration will often look like: 

<preActions>
  <preAction>
    <type>io.yupiik.fusion.documentation.ConfigurationDocumentationGenerator</type>
  </preAction>
</preActions>

Configuration:

Name Description

includeEnvironmentNames

Should environment names of the keys be shown or ignored. Default false.

module

Title name for list formatter.

output

When to generate the asciidoc file, by default - when not set - it uses $source/content/_partials/generated/documentation.$module.adoc.

formatter

Can be list for a plain asciidoc list (with h1/h2 titles), table for a table and definitionlist for a definition list. Data are globally the same but depending your configuration it can be easier to read in one style or another.

urls

If not set META-INF/fusion/configuration/documentation.json is loaded from the classpath else the url to convert to asciidoc (same format).

roots

If you don't want to generate the configuration for all classes, the root classes to include from the JSON file (urls).

CLI documentation

io.yupiik.fusion.documentation.CliDocumentationGenerator enables to generate documentation in asciidoc for CLI modules.

If you use Yupiik tools minisite, configuration will often look like: 

<preActions>
  <preAction>
    <type>io.yupiik.fusion.documentation.CliDocumentationGenerator</type>
  </preAction>
</preActions>

Configuration:

Name Description

indexHeader

Header - top content - of the index page.

indexName

Name if the index page listing commands, defaults to index.adoc. Can also include some relative path to render it in another folder but ensure to adjust indexRelativePath then.

indexRelativePath

Prefix to links to the command documentation, this is useful when the index page is generated in partials directory for example and you include it in another page.

package

If set enables to filter the commands included by package.

outputBase

Base directory where to generate the commands and command index documents.
NOTE

the generator starts a fusion container disabling Start and Stop events so take care if it needs some caution (static code for example). To know you are in this mode you can use Configuration and io.yupiik.fusion.documentation.CliDocumentationGenerator key, if set you are in generator mode.

Navigation