開發者 APIDeveloper API

這頁給想串接 ServerAPI 的插件開發者，講怎麼把它加進你的專案、以及可用的 API。完整的教學、模式怎麼選、回傳型別，見第三方站點串接。

導入依賴

你需要在編譯時看得到 kevin.serverapi.api 底下的 ServerApiRegistry 與 CustomStation。兩種做法擇一，都不要把 ServerAPI 打包（shade）進你的 jar，它執行期由伺服器上的插件提供。

做法一：JitPack。加 repository 和 com.github 座標，第一次編譯時 JitPack 會自動幫你建好：

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.Kevin28576</groupId>
    <artifactId>ServerAPI</artifactId>
    <version>v1.1.0</version>
    <scope>provided</scope>
    <exclusions>
        <exclusion><groupId>*</groupId><artifactId>*</artifactId></exclusion>
    </exclusions>
</dependency>

version 填 GitHub 上的 tag 名（例如 v1.1.0）。exclusions 把 ServerAPI 自己的相依全排掉，因為你只要那兩個介面。

做法二：直接複製。把 ServerApiRegistry.java 與 CustomStation.java 複製進你的專案。它們只依賴 Bukkit 的 Plugin，複製過去就能編。

ServerApiRegistry

ServerAPI 啟用時會把它登記到 Bukkit 的 ServicesManager，你在自己的 onEnable()（會晚於 ServerAPI）取得：

var rsp = getServer().getServicesManager().getRegistration(ServerApiRegistry.class);
if (rsp == null) return;                 // 沒裝 ServerAPI，就當作沒這回事
ServerApiRegistry api = rsp.getProvider();

方法	作用
`register(CustomStation)`	註冊或以相同名稱更新一個站點
`unregister(String)`	取消註冊；停止對外但保留設定檔
`isServed(String)`	查詢站點是否正對外提供（已啟用且掛上）

CustomStation.builder

方法	必填	作用
`builder(name, plugin)`	是	開始建立，指定站點名稱與來源插件
`.supplier(fn)`	是	回傳資料的函式，純 Java 即可
`.description(text)`	否	顯示在 `/api/v1` 索引上的說明
`.cached(seconds)`	否	快照模式：主執行緒每幾秒呼叫一次
`.async()`	否	即時模式（預設）：HTTP 執行緒上呼叫
`.build()`	是	產生 CustomStation，交給 register

不加 .async() 或 .cached() 時，預設就是即時模式。什麼時候該用哪個、供應者能回傳哪些型別，見第三方站點串接。

This page is for plugin developers integrating with ServerAPI: how to add it to your project, and the API you get. For the full walkthrough, choosing a mode, and return types, see Third-party stations.

Adding the dependency

You need ServerApiRegistry and CustomStation from kevin.serverapi.api at compile time. Pick one of two ways, and do not shade ServerAPI into your jar; it is provided at runtime by the plugin on the server.

Option 1: JitPack. Add the repository and the com.github coordinates; JitPack builds it for you on first use:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.Kevin28576</groupId>
    <artifactId>ServerAPI</artifactId>
    <version>v1.1.0</version>
    <scope>provided</scope>
    <exclusions>
        <exclusion><groupId>*</groupId><artifactId>*</artifactId></exclusion>
    </exclusions>
</dependency>

version is the GitHub tag name (e.g. v1.1.0). The exclusions strip ServerAPI's own dependencies, since you only want the two interfaces.

Option 2: copy the classes. Copy ServerApiRegistry.java and CustomStation.java into your project. They depend only on Bukkit's Plugin, so they compile as-is.

ServerApiRegistry

ServerAPI registers it into Bukkit's ServicesManager when it enables. Look it up in your own onEnable() (which runs after ServerAPI):

var rsp = getServer().getServicesManager().getRegistration(ServerApiRegistry.class);
if (rsp == null) return;                 // No ServerAPI installed, just skip it
ServerApiRegistry api = rsp.getProvider();

Method	What it does
`register(CustomStation)`	Register, or update a station of the same name
`unregister(String)`	Stop serving it, but keep the config file
`isServed(String)`	Whether the station is currently served (enabled and mounted)

CustomStation.builder

Method	Required	What it does
`builder(name, plugin)`	Yes	Start building; the station name and owning plugin
`.supplier(fn)`	Yes	The function returning the data, plain Java
`.description(text)`	No	Shown in the `/api/v1` index
`.cached(seconds)`	No	Cached mode: called on the main thread every few seconds
`.async()`	No	Live mode (default): called on the HTTP thread
`.build()`	Yes	Produce the CustomStation to pass to register

With neither .async() nor .cached(), the default is live mode. For when to use which, and which return types the supplier may produce, see Third-party stations.