Livedoc endpoint shows wrong livedoc version and badly parseable build date

[ST-DDT]

Describe the bug

In the generated /jsondoc endpoint the outputs a different version number than the one specified in the artifact. The build date is written in an english format that is intended for humans, but since it is a data endpoint it should output a format understandable by computers.

{
    "livedocInfo": {
        "version": "4.4.2",
        "buildDate": "May 5, 2018"
    },
}

Expected behavior

{
    "livedocInfo": {
        "version": "4.5.0",
        "buildDate": "2018-05-21"
    },
}

Screenshots

Environment/Context

I use Livedoc in a Spring 5.0.x Environment with Maven.

[INFO] +- org.hildan.livedoc:livedoc-springmvc:jar:4.5.0:compile
[INFO] |  \- org.hildan.livedoc:livedoc-core:jar:4.5.0:compile
[INFO] |     +- org.hildan.livedoc:livedoc-annotations:jar:4.5.0:compile
[INFO] |     +- org.hildan.generics:generics-explorer:jar:1.1.0:runtime
[INFO] |     \- org.freemarker:freemarker:jar:2.3.20:runtime
[INFO] +- org.hildan.livedoc:livedoc-javadoc-processor:jar:4.5.0:provided
[INFO] |  \- com.github.therapi:therapi-runtime-javadoc-scribe:jar:0.6.0:provided

Solution

To avoid such issues (due to wrongly generated meta-data files) you could switch the the meta data that are stored in the META-INF/MANIFEST.mf file (needs to be enabled in your build config)

Here an example from Postgresql's jdbc driver:

Manifest-Version: 1.0
Bnd-LastModified: 1521130596407
Build-Jdk: 1.8.0_151
Built-By: travis
Bundle-Activator: org.postgresql.osgi.PGBundleActivator
Bundle-Copyright: Copyright (c) 2003-2015, PostgreSQL Global Development
  Group
Bundle-Description: Java JDBC 4.2 (JRE 8+) driver for PostgreSQL databas
 e
Bundle-DocURL: https://jdbc.postgresql.org/
Bundle-License: https://jdbc.postgresql.org/about/license.html
Bundle-ManifestVersion: 2
Bundle-Name: PostgreSQL JDBC Driver JDBC42
Bundle-SymbolicName: org.postgresql.jdbc42
Bundle-Vendor: PostgreSQL Global Development Group
Bundle-Version: 42.2.2
Created-By: Apache Maven Bundle Plugin
[...]
Implementation-Title: PostgreSQL JDBC Driver - JDBC 4.2
Implementation-Vendor: PostgreSQL Global Development Group
Implementation-Vendor-Id: org.postgresql
Implementation-Version: 42.2.2
[...]
Specification-Title: JDBC
Specification-Vendor: Oracle Corporation
Specification-Version: 4.2
Tool: Bnd-2.4.0.201411031534

Then you can access these meta information by simply invoking. getClass().getPackage().getImplementationVersion()

[joffrey-bion]

Thanks for opening this issue. I realized the meta data was wrong when building the demo docker image during a break this morning.

Not sure why it is so, though. It seems ok when building the multiproject, not depending on the jar itself.

Using the manifest is a very good suggestion. I'll try to give it a go after I find out what happened to the meta data of the artifact.

[joffrey-bion]

Ok I found out the problem regarding the deployment of an artifact with stale resources. This is due to this gradle "bug": https://github.com/gradle/gradle/issues/808 https://github.com/gradle/gradle/issues/861

Following the suggestions there, I think I have some changes that could prevent this from happening again. Anyway, I should build and upload artifacts from a clean environment to avoid this kind of issues next time.

Using the manifest for the version looks nice, but there is no easy way to get the build date out of it. Getting the manifest seems to be a not-so-easy task after all. Also, this would only work when running livedoc from a JAR. This is the case most of the time except during local development, and thus will make local testing more complicated.

I guess I'll stick to the properties file for now as far as reading the info is concerned, but I'll generate a more complete manifest anyway for the sake of better packaging.