APIdia

[Stewori]

Hallo zusammen, hier möchte ich mein aktuelles Projekt vorstellen, das hoffentlich für viele nützlich sein wird:

APIdia

apidia.net

ist ein Browser für (derzeit) Java API, ähnlich wie javadoc.io, aber mit verbessertem Design.
Insbesondere lässt sich API mittels Seitennavigation browsen - ein Fähigkeit die im normalen Javadoc mit Java 12 abgeschafft wurde (weil Frames nicht zukunftsfähig sind/deprecated in html 5; auf APIdia wird der Effekt ohne Frames realisiert). Die Browser-URL stellt dabei zu jedem Zeitpunkt einen parametrisierten Link auf den aktuellen Zustand der "Frames" dar. Wenn man Links in neuen Tabs öffnet, bleibt die Navigation ebenfalls erhalten.

Darüber hinaus gibt es viele kleine Features, z.B. Mouseover-Tooltips für Methodenparameter oder dass jede Methode einen Hinweis mit Link hat, falls sie eine andere Methode überschreibt, implementiert oder verbirgt.

Im Menü oben rechts kann man Sichtbarkeit von private/protected etc Klassen und Members konfigurieren. Die Ansicht der Webseite passt sich dabei sofort entsprechend an. Wer also z.B. als Core-dev oder Contributor an einem Projekt arbeitet kann APIdia somit auch nutzen, um sich in der internen API zu orientieren.

Wie in Javadoc gibt es ein Suchfeld zur Indexsuche bzw. Jump-access, das auf APIdia allerdings Regex unterstützt.
(Hinweis: Leerzeichen werden dabei als .* gewertet, wodurch man lange Namen segmentweise abkürzen kann. Leerzeichen verhalten sich somit wie eine "Und"-Verknüpfung der Suchterme, die allerdings die Reihenfolge respektiert.)
Das Dropdown mit Suchergebnissen hat ein Designfeature, das ich hervorheben will, aber schlecht in Worte fassen kann. Schaut es euch am besten einfach an.

Derzeit stellt APIdia die einzige mir bekannte Möglichkeit dar, das aktuelle Java 22 mit vernünftiger, projektweiter Seitennavigation zu durchstöbern (https://apidia.net/java/OpenJDK). Darüber hinaus sind mehrere hundert Maven-Artefakte gehostet; schreibt mir hier ggf als Reply wenn euch da was fehlt. Alle gehosteten Projekte sind konsequent miteinander kreuzverlinkt.

Cross-version browsing ist in Vorbereitung, es ist allerdings ein "non-goal", ganz Maven Central mit allen Versionen zu hosten. Es werden jeweils die neusten Versionen und ausgewählte, wichtige Altversionen gehostet werden. Von der Java standard library ist derzeit noch die aktuelle LTS drin unter https://apidia.net/java/OpenJDK/1.21

Und natürlich ist das ganze Projekt kostenlos, ohne Tracking, ohne Cookies, GDPR-konform, lightweight und schnell.
(Ja, in der privacy policy wird auf Cookies hingewiesen, weil ich dachte, ich würde ein Session-Cookie brauchen. Bisher geht es jedoch ohne und wird wohl auch so bleiben.)
Um ganz transparent zu sein: derzeit ist die Seite werbefrei, ggf wird in Zukunft zur Refinanzierung der Betriebskosten allerdings eine freundliche, unaufdringliche Werbung eingeblendet, wie man es von Readthedocs oder Stackoverflow kennt. Keinesfalls mit Tracking oder Animation. Ich hoffe, das ist zumutbar und es ist mir einfach die liebere Variante als wikipedia-mäßig Spendenaufrufe zu setzen. Aber schreibt gerne, was ihr darüber denkt und auch sonst über die Seite.

Könnt ihr euch vorstellen, die Seite zu nutzen? Was findet ihr gut, was würdet ihr euch ggf anders wünschen? Wenn ihr die Seite unterstützen wollt, empfehlt sie bitte weiter

Viel Spaß beim API-surfen!

 

[mihe7]

Zunächst einmal gefällt mir das sehr gut, es ist schnell, die auf den Seiten Verweise funktionieren (wobei auch immer die Frage ist: auf welche Version wird verwiesen, wenn mal mehrere Versionen vorhanden sind). Die Suche scheint noch Macken zu haben: wenn ich nach einer Methode suche lande ich immer nur in der Klasse, aber nicht an der Methode und manchmal wird auch nicht die Klasse geöffnet.
(Update: Problem wurde inzwischen behoben)

Beispiel: wenn ich in der JPA nach "from" (ohne Anführungszeichen) suche und den CriteriaUpdate-Eintrag öffne, lande ich in CriteriaUpdate, nicht aber bei der betreffenden from-Methode. Wenn ich dann erneut nach from suche und dann die Methode von AbstractQuery auswähle, passiert nix. Witzigerweise: gerade hat es jetzt funktioniert und ich bin auch in der from-Methode gelandet. Wieder das from von CriteriaUpdate ausgewählt: nix passiert. Seltsam.

Das aber nur nebenbei, weil es mir gerade aufgefallen ist. Zurück zum Thema: Ich weiß nicht, wie es anderen geht, aber ich verwende die HTML-basierten API-Docs von Java (Standard APIs) relativ oft und ich habe mich fürchterlich geärgert, als die Frames entfernt wurden. So gesehen wäre das das optimale Tool für mich. Wäre... wenn ich es vor zwei, drei Jahren gehabt hätte.

Mittlerweile bin ich an die framelose Variante gewöhnt und die Suche habe ich im Browser integriert. Ich öffne also nicht erst irgendeine Website und suche dort, sondern tippe in der Adressleiste des Browsers "j <suchbegriff>" und lande auf der Ergebnisseite der API-Docs, klicke dort auf den betreffenden Link und sehe, was ich sehen möchte. Von dort aus verwende ich das Suchfeld der API-Docs höchstens, um mal nach einer anderen Klasse oder einer Methode zu suchen.

Es ist also schwer zu sagen, ob ich das Tools für die Standard API verwenden werde. Eher nicht. Bei anderen APIs kann ich mir das allerdings durchaus vorstellen.

Unabhängig davon: Respekt! Und vielen Dank für das schöne Projekt.

 

[LimDul]

Coole Sache auf jeden Fall. Größtes Problem sehe ich, dran zu denken, wenn ich mal wieder API-Doc suche. Ich kann verstehen, dass du nicht von allen Maven Central Projekten alle Versionen drin haben willst - das kostet vermutlich zu viele Resourcen. Was aber schön wäre, eine Möglichkeit strukturiert weitere Maven Central Projekte zu ergänzen - nicht per Kontaktformular, sondern am besten mit einem Formular wo ich nur den Link einfüge und auf absenden klicke. Dann kann das entweder automatisch verarbeitet werden oder noch mal geprüft werden, wenn zu viel Sorge vor Spam besteht.

Sprich, ich möchte als Anwender möglichst einfach API Doc von Maven Central hinzufügen können und wünsche mir einen Workflow wo das sehr fix passiert und nicht davon abhängig ist, dass du neben dem eigentlichen Job genug Zeit & Lust hast.

 

[Stewori]

Die Suche scheint noch Macken zu haben

Ich glaube, ich habe das Problem behoben. Teste bitte nochmal (vorher apidia.net/rs/navscript.js refreshen, bei Bedarf ggf Cache leeren) (Auf meinem Standardbrowser hatte es immer funktioniert, darum war mir das Problem nicht aufgefallen, konnte es nach dem Hinweis aber in nem anderen Browser reproduzieren.) Falls es tatsächlich behoben ist, würde ich dich bitten, deinen Beitrag zu editieren und "(Update: Problem wurde inzwischen behoben)" oder so ähnlich einzufügen, für Leute, die nicht die Replies lesen...

So gesehen wäre das das optimale Tool für mich. Wäre... wenn ich es vor zwei, drei Jahren gehabt hätte.

Habs leider nicht schneller geschafft 😅

Mittlerweile bin ich an die framelose Variante gewöhnt und die Suche habe ich im Browser integriert. Ich öffne also nicht erst irgendeine Website und suche dort, sondern tippe in der Adressleiste des Browsers "j <suchbegriff>" und lande auf der Ergebnisseite der API-Docs

Darf ich fragen, wie du diese Integration realisierst? Mit einem Plugin? Oder bietet der Browser selbst so eine Integration? Kann ich auf die Weise auch die APIdia-Suche in meinem Browser integrieren?

Bei anderen APIs kann ich mir das allerdings durchaus vorstellen.

Unabhängig davon: Respekt! Und vielen Dank für das schöne Projekt.

Klar, jeder soll APIdia so nutzen, wie es ihm oder ihr am nützlichsten ist. Danke auf jeden Fall für das Feedback und den Bug-report! Ich werde bald auch einen Issue-Tracker eröffnen, bin noch am überlegen wo am besten.

 

[Stewori]

Coole Sache auf jeden Fall. Größtes Problem sehe ich, dran zu denken, wenn ich mal wieder API-Doc suche.

Vielleicht ist ja noch ein ehrenvoller Platz in den Bookmarks frei 🙃

Ich kann verstehen, dass du nicht von allen Maven Central Projekten alle Versionen drin haben willst - das kostet vermutlich zu viele Resourcen.

Darüber hinaus ist Maven Central auch voll von toten Projekten, z.B. die seit zig Jahren nicht mehr weiterentwickelt werden, oder inoffiziellen Forks oder Projekten von experimentellem Charakter, Test-setups, und ähnliches. Schwerpunkt liegt erstmal darauf, in gewissem Sinne "kanonische" Projekte zu unterstützen, soweit der Begriff irgendwie Sinn macht. Zumindest die toten Projekte kommen durchaus nach APIdia, sofern sie als Dependencies noch Relevanz haben. Die anderen nur auf besonderen Wunsch.

Was aber schön wäre, eine Möglichkeit strukturiert weitere Maven Central Projekte zu ergänzen - nicht per Kontaktformular, sondern am besten mit einem Formular wo ich nur den Link einfüge und auf absenden klicke. Dann kann das entweder automatisch verarbeitet werden oder noch mal geprüft werden, wenn zu viel Sorge vor Spam besteht.
Sprich, ich möchte als Anwender möglichst einfach API Doc von Maven Central hinzufügen können und wünsche mir einen Workflow wo das sehr fix passiert und nicht davon abhängig ist, dass du neben dem eigentlichen Job genug Zeit & Lust hast.

Den Wunsch verstehe ich, absolut. Das Kontaktformular ist eine Übergangslösung. Falls es das einfacher macht, kann ich Angabe von Name/Email optional machen.
Den Prozess voll zu automatisieren ist nicht so einfach, da ich noch nicht jede exotische Konfiguration die einem auf Maven Central irgendwo unterkommt verarbeiten kann. Bei manchen Projekten sind die Sources auch nicht auf Maven Central; einmal konnte ich die sogar nur noch aus der Wayback-Machine holen (Colt). Außerdem muss ich oft noch manuell die Lizenzen checken, wenn die kein bekannter Standardtext sind.
Die volle Automatisierung wird kommen, braucht aber noch Arbeit. Bis dahin möchte ich jeden ermuntern, das was da ist - das MVP, wenn man so will - schonmal zu nutzen und Wunschprojekte über den Kontakt mitzuteilen.

 

[mihe7]

Falls es tatsächlich behoben ist, würde ich dich bitten, deinen Beitrag zu editieren und "(Update: Problem wurde inzwischen behoben)" oder so ähnlich einzufügen, für Leute, die nicht die Replies lesen...

Scheint jetzt zu funktionieren. Editieren kann ich den Beitrag nicht mehr, aber vielleicht findet @KonradN die Zeit.

Darf ich fragen, wie du diese Integration realisierst? Mit einem Plugin? Oder bietet der Browser selbst so eine Integration? Kann ich auf die Weise auch die APIdia-Suche in meinem Browser integrieren?

https://www.java-forum.org/thema/java-19-javadocs-browserintegration.200756/

 

[Stewori]

@mihe7 Danke nochmal für den Bug-report und das schnelle Nachtesten. Bin recht neu hier und dachte, man könne Beiträge editieren (wie bei Github, Stack-Overflow). Aber schön, dass es trotzdem geklappt hat: Danke, @KonradN !
Auch danke für den Hinweis mit der Browser-Integration. Eine Suchseite mit "?q=..." url-Parameter kann ich für APIdia auch bereitstellen, zumindest projektweise. Über alle Projekte hinweg zu suchen wäre etwas schwieriger, aber auch das lässt sich ggf. machen. In nächster Zeit werde ich nicht dazu kommen, aber ich gebe hier auf jeden Fall nochmal Rückmeldung, sobald der "Trick" auch bei APIdia unterstützt wird.
Das soll natürlich niemanden auffordern zu APIdia zu "wechseln" Aber diese Integration zu ermöglichen ist ja so oder so sinnvoll.

 

[Stewori]

Es gibt jetzt einen Issue-Tracker für APIdia. Ich hatte lange vorgehabt, einen eigenen, unabhängigen Issue-Tracker zu betreiben, habe mich jetzt bis auf Weiteres aber doch für eine Präsenz auf Github entschieden. Dort halte ich die Hemmschwelle, Issues zu posten für deutlich geringer, da die meisten vermutlich bereits einen Account haben. Also, ab jetzt können Issues (und natürlich auch Feature Requests etc) unter https://github.com/APIdia-net/apidia.net gemeldet werden.