• Menu

    Documentation

    Documentation module provides some tasks you can integrate with Yupiik minisite - or any other living documentation. It aims at consuming the JSON metadata generated by Fusion to convert it to a documentation content.

    Dependency

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

    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.DocumentationGenerator 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.DocumentationGenerator</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 confguration 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).

    Navigation