Shields: Add for javadoc.io

[jinahya]

javadoc.io provides javadocs of artifacts available on the central.

Please consider adding a predefined badge for this.

[jinahya]

I'm not good at JavaScript. Please check following code out from the maven-central's code.

// javadoc.io                                                                                                                                              
camp.route(/^\/javadoc.io\/v\/(.*)\/(.*)\.(svg|png|gif|jpg|json)$/,
cache(function(data, match, sendBadge, request) {
  var groupId = match[1]; // eg, `com.google.inject`                                                                                                       
  var artifactId = match[2]; // eg, `guice`                                                                                                                
  var format = match[3] || "gif"; // eg, `guice`                                                                                                           
  var query = "g:" + encodeURIComponent(groupId) + "+AND+a:" + encodeURIComponent(artifactId);
  var apiUrl = 'https://search.maven.org/solrsearch/select?rows=1&q='+query;
  var badgeData = getBadgeData('javadoc-io', data);
  request(apiUrl, { headers: { 'Accept': 'application/json' } }, function(err, res, buffer) {
    if (err != null) {
      badgeData.text[1] = 'inaccessible';
      sendBadge(format, badgeData);
      return;
    }
    try {
      var data = JSON.parse(buffer);
      var version = data.response.docs[0].latestVersion;
      badgeData.text[1] = 'v' + version;
      if (version === '0' || /SNAPSHOT/.test(version)) {
        badgeData.colorscheme = 'orange';
      } else {
        badgeData.colorscheme = 'blue';
      }
      badgeData.link = 'http://www.javadoc.io/doc/' + groupId + '/' + artifactId + '/' + version;
      sendBadge(format, badgeData);
    } catch(e) {
      badgeData.text[1] = 'invalid';
      sendBadge(format, badgeData);
    }
  });
}));

[espadrine]

Thanks a lot for the suggestion, and the patch!

Do you want to produce a PR, so that I can review it in the conventional GitHub way, or do you want me to produce a code review in a comment on this issue?

In either case, here's a preliminary review:

var format = match[3] || "gif"; // eg, `guice`

You don't want to put || "gif" here. Exceptions are already taken care of. Also, the comment is misleading. format cannot be "guice".

var apiUrl = 'https://search.maven.org/solrsearch/select?rows=1&q='+query;

Please put spaces around the +.

var badgeData = getBadgeData('javadoc-io', data);

Do you want to have javadoc.io here instead?

badgeData.link = 'http://www.javadoc.io/doc/' + groupId + '/' + artifactId + '/' + version;

There is no link on badgeData. If you want to add a link, some badge styles (well, currently, only social) allow you to make the left-hand-side of the badge link to somewhere, and the right-hand-side to link somewhere (to a potentially different location). If you want to do so, you can set badgeData.links = [firstLink, secondLink];. For instance, the Twitter Follow badge has a left link point to the follow Twitter intent, and the right link point to a list of followers. If you have no idea what to put on the right link, you can set badgeData.links to a list of a single element.

You also probably want to have an example badge on the front page, which you can do by adding one to /try.html. You can use /javadoc.io/v/com.google.inject/guice.svg as example.

[ben-manes]

fyi, as a stopgap for direct support there is another provider.

[Grogs]

I am one of the developers of javadoc.io. Coincidentally I added support to create shields.io badges last week. There's now a little form on the homepage to create badges with a little HTML or Markdown snippet. Our endpoint issues a redirect to a shields.io image.

Is there a better/preferred way of doing this? Happy to help out if there's anything that can be done on the javadoc.io end.

[jinahya]

Great!!! I checked the form. It's beautiful. This issue can be closed, I believe.

[pushbit]

Can we leave this open so that an official entry is eventually added to the shields.io list?

[v-nisidh]

Unfortunately I saw old badge after releasing new release on Maven. I saw similar problem on our last release. Generally it will show old badge for ~ 2 days and then GitHub pages refresh the image. I did not see this with maven-badges.herokuapp....

https://github.com/Microsoft/mssql-jdbc

Interesting thing is on normal browser it come up with appropriate badge.
http://javadoc.io/badge/com.microsoft.sqlserver/mssql-jdbc.svg

While on GitHub, it is showing old badge but with correct link. Is it due to some redirection or appropriate cache-content headers ?

[ben-manes]

Yes, the badge provider needs to set the expiry header, e.g. https://github.com/valery1707/javadoc-badge/issues/2

[paulmelnikow]

Hi @v-nisidh, thanks for the report and the info. Would you mind opening a new issue and describing further the behavior you're seeing, and @ben-manes elaborating on the fix you're suggesting?

[ben-manes]

The fix is to set the Cache-Control header's max-age to a shorter value, e.g. 1 hour. It sounds like you are relying on Github's default expiration time, as the headers show it is set to 24 hours.