Implementation:Treeverse LakeFS Java SDK OpenAPI Spec
| Knowledge Sources | |
|---|---|
| Domains | API, SDK Generation, Java |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
The openapi.yaml file is the master OpenAPI 3.0 specification that defines the entire lakeFS HTTP API and serves as the source from which the Java SDK client is auto-generated.
Description
This is an 11,941-line OpenAPI 3.0 specification located in the Java client directory. It describes every HTTP endpoint, request/response schema, and authentication mechanism for the lakeFS REST API (version 1.0.0). The specification is served at the base path /api/v1 and is licensed under Apache 2.0.
The spec defines five authentication schemes:
- jwt_token - JWT bearer token authentication
- basic_auth - HTTP basic authentication
- cookie_auth - Cookie-based session authentication
- oidc_auth - OpenID Connect authentication
- saml_auth - SAML-based authentication
Key API endpoint groups include setup operations (/setup_lakefs, /setup_comm_prefs), repository management, branch operations, object storage, commit workflows, merge operations, action runs, and access control (users, groups, policies).
The file uses $ref pointers to reference reusable component schemas defined in the components/schemas section (e.g., Error, SetupState, CommPrefsInput).
Usage
This file is consumed by OpenAPI code generators (such as openapi-generator) to produce the Java SDK client classes in the apigen package. It should be updated whenever the lakeFS API changes, and the Java SDK should be regenerated afterward. It is the single source of truth for the Java client's HTTP contract.
Code Reference
Source Location
- Repository: Treeverse_LakeFS
- File: clients/java/api/openapi.yaml
- Lines: 1-11941
Signature
openapi: 3.0.0
info:
description: lakeFS HTTP API
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
title: lakeFS API
version: 1.0.0
servers:
- description: lakeFS server endpoint
url: /api/v1
security:
- jwt_token: []
- basic_auth: []
- cookie_auth: []
- oidc_auth: []
- saml_auth: []
Import
# Used as input to openapi-generator-cli
openapi-generator-cli generate -i clients/java/api/openapi.yaml -g java ...
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| openapi.yaml | YAML file | Yes | The OpenAPI 3.0 specification file consumed by the code generator |
| Generator config | JSON/YAML | No | Optional generator configuration overriding default code generation settings |
Outputs
| Name | Type | Description |
|---|---|---|
| Java SDK classes | .java files | Auto-generated API client classes, model objects, and configuration |
| API documentation | HTML/Markdown | Generated API reference documentation |
Usage Examples
# Example endpoint definition from the spec
paths:
/setup_lakefs:
get:
operationId: getSetupState
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/SetupState'
description: lakeFS setup state
"429":
description: too many requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Internal Server Error