Final 1.0.0 Release

Took 44 minutes

README.md

@@ -1 +1,95 @@
-# Hangar4J
+# Hangar4J
+
+A Java wrapper to easily access PaperMC's [Hangar API](https://hangar.papermc.io/api-docs).
+This wrapper is still in development, so more features will be added in the future.
+
+At the moment, you can retrieve the following information:
+* Projects
+* Versions
+* Users
+
+*Disclaimer: This wrapper is not affiliated with PaperMC or Hangar in any way.*
+## How to Use
+Firstly, you should initialize a ```HangarClient``` instance with your API key. You can get an API key from your Hangar profile.
+If you don't contain an API key, you can still use the wrapper, but you will share api limits with other users using the public API.
+
+The methods below are in the ```HangarClient``` class and will return their respective objects.
+
+### Initializing HangarClient
+Using an API key and a custom user agent (recommended):
+```java
+HangarClient HangarClient("API_KEY", "USER_AGENT")
+```
+Without an API key and using public api and sharing its limits with other users (not recommended):
+```java
+HangarClient HangarClient("USER_AGENT")
+```
+
+### Projects
+Get a project by its author and slug
+```java
+Project getProject(String author, String slug)
+```    
+Get a list of projects
+```java
+Projects getProjects(boolean orderWithRelevance, int limit, int offset)
+Projects getProjects(int limit, int offset)
+```
+Get the total amount of projects
+```java
+int getTotalProjectCount()
+```
+
+### Versions
+Get a list of versions of a project
+```java
+Versions getVersions(String author, String slug)
+Versions getVersions(HangarProject project)
+```
+Get a specific version of a project
+```java
+Version getVersion(String author, String slug, String version)
+Version getVersion(HangarProject project, String version)
+```
+### Users
+Get a user by their username
+```java
+User getUser(String user)
+```
+## Installation
+
+The latest version can be found in the releases tab on the right.
+
+### Maven
+```xml
+<repository>
+    <id>jitpack.io</id>
+    <url>https://jitpack.io</url>
+</repository>
+```  
+```xml
+<dependency>
+    <groupId>com.github.xmrafonso</groupId>
+    <artifactId>hangar4j</artifactId>
+    <version>VERSION</version>
+</dependency>
+```
+
+#### Gradle
+```kt
+repositories {
+    maven("https://jitpack.io")
+}
+
+dependencies {
+    implementation("com.github.xmrafonso:hangar4j:VERSION")
+}
+```  
+
+## Contributing
+
+Contributions are always welcome. Please open a pull request or an issue if you have any ideas or suggestions.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/xMrAfonso/Hangar4J/blob/main/LICENSE) file for details.

src/main/java/me/mrafonso/hangar4j/HangarClient.java

@@ -19,6 +19,9 @@
 import java.util.Date;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * HangarClient is the main class of the library. It is used to make requests to the Hangar API.
+ */
 public class HangarClient {
     private static final HttpClient client = HttpClient.newBuilder()
             .version(HttpClient.Version.HTTP_1_1)
@@ -29,22 +32,44 @@ public class HangarClient {
     private final String userAgent;
     private final String apiKey;
 
+    /**
+     * Creates a new HangarClient instance with the specified API key and user agent.
+     * This constructor is used when you have an API key and want to use the authenticated API.
+     * You will have your own separate api limits.
+     *
+     * @param apiKey The API key to use for requests.
+     * @param userAgent The user agent to use for requests.
+     */
     public HangarClient(String apiKey, String userAgent) {
         this.apiKey = apiKey;
         this.userAgent = userAgent + " (Hangar4J)";
     }
 
+    /**
+     * Creates a new HangarClient instance with the specified user agent.
+     * This constructor is used when you don't have an API key and want to use the public API.
+     * WARNING: You will share api limits with other users.
+     *
+     * @param userAgent The user agent to use for requests.
+     */
     public HangarClient(String userAgent) {
         this.apiKey = null;
         this.userAgent = userAgent + " (Hangar4J)";
     }
 
+
+    /*
+     * Checks if the JWT token has expired.
+     */
     private boolean isJWTExpired() {
         Date expiresAt = jwt.getExpiresAt();
         jwt.getToken();
         return expiresAt.before(new Date());
     }
 
+    /*
+     * Sends a request to the Hangar API and does some basic error handling.
+     */
     private CompletableFuture<HttpResponse<String>> sendAPIRequest(String path, RequestType type) {
         HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
                 .uri(URI.create(API_URL + path))
@@ -63,6 +88,11 @@ private CompletableFuture<HttpResponse<String>> sendAPIRequest(String path, Requ
         return client.sendAsync(request, HttpResponse.BodyHandlers.ofString());
     }
 
+
+    /**
+     * Updates the JWT token used for authentication.
+     * This method is called automatically when making a request to the API if the JWT token has expired.
+     */
     public void updateJWT() {
         sendAPIRequest("/authenticate?apiKey=" + apiKey, RequestType.POST)
                 .thenApply(response -> {
@@ -73,12 +103,27 @@ public void updateJWT() {
                 .join();
     }
 
+    /**
+     * Retrieve information about a specific project.
+     *
+     * @param author The author of the project.
+     * @param slug The slug of the project.
+     * @return HangarProject object containing information about the project.
+     */
     public HangarProject getProject(String author, String slug) {
         return sendAPIRequest("/projects/" + author + "/" + slug, RequestType.GET)
                 .thenApply(response -> gson.fromJson(response.body(), HangarProject.class))
                 .join();
     }
 
+    /**
+     * Retrieve a list containing several projects.
+     *
+     * @param orderWithRelevance Whether to order the projects with relevance or not.
+     * @param limit The maximum amount of projects to return.
+     * @param offset The offset to start from.
+     * @return HangarProjects object containing a list of projects.
+     */
     public HangarProjects getProjects(boolean orderWithRelevance, int limit, int offset) {
         if (limit > 25) {
             throw new IllegalArgumentException("Unable to make requests with a limit higher than 25. Currently: " + limit);
@@ -88,38 +133,84 @@ public HangarProjects getProjects(boolean orderWithRelevance, int limit, int off
                     .join();
     }
 
+    /**
+     * Retrieve a list containing several projects.
+     *
+     * @param limit The maximum amount of projects to return.
+     * @param offset The offset to start from.
+     * @return HangarProjects object containing a list of projects.
+     */
     public HangarProjects getProjects(int limit, int offset) {
         return getProjects(false, limit, offset);
     }
 
+    /**
+     * Retrieve information about a specific user.
+     *
+     * @param user The username of the user.
+     * @return HangarUser object containing information about the user.
+     */
     public HangarUser getUser(String user) {
         return sendAPIRequest("/users/" + user, RequestType.GET)
                 .thenApply(response -> gson.fromJson(response.body(), HangarUser.class))
                 .join();
     }
 
+    /**
+     * Retrieve information about a specific version of a specific project.
+     *
+     * @param author The author of the project.
+     * @param slug The slug of the project.
+     * @param version The version of the project.
+     * @return HangarVersion object containing information about the version.
+     */
     public HangarVersion getVersion(String author, String slug, String version) {
         return sendAPIRequest("/projects/" + author + "/" + slug + "/versions/" + version, RequestType.GET)
                 .thenApply(response -> gson.fromJson(response.body(), HangarVersion.class))
                 .join();
     }
 
+    /**
+     * Retrieve information about a specific version of a specific project.
+     *
+     * @param hangarProject The HangarProject object.
+     * @param version The version of the project.
+     * @return HangarVersion object containing information about the version.
+     */
     public HangarVersion getVersion(HangarProject hangarProject, String version) {
         Namespace namespace = hangarProject.getNamespace();
         return getVersion(namespace.getOwner(), namespace.getSlug(), version);
     }
 
+    /**
+     * Retrieve a list containing several versions of a specific project.
+     *
+     * @param author The author of the project.
+     * @param slug The slug of the project.
+     * @return HangarVersions object containing a list of versions.
+     */
     public HangarVersions getVersions(String author, String slug) {
         return sendAPIRequest("projects/" + author + "/" + slug + "/versions/", RequestType.GET)
                 .thenApply(response -> gson.fromJson(response.body(), HangarVersions.class))
                 .join();
     }
 
+    /**
+     * Retrieve a list containing several versions of a specific project.
+     *
+     * @param hangarProject The HangarProject object.
+     * @return HangarVersions object containing a list of versions.
+     */
     public HangarVersions getVersions(HangarProject hangarProject) {
         Namespace namespace = hangarProject.getNamespace();
         return getVersions(namespace.getOwner(), namespace.getSlug());
     }
 
+    /**
+     * Retrieve the total amount of projects present in Hangar.
+     *
+     * @return The total amount of projects as an integer.
+     */
     public int getTotalProjects() {
         return getProjects(1, 0).getPagination().getCount();
     }