From 2c26b4ece13994b975aa326566d9535557d2a814 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 28 Sep 2025 20:21:00 +0000 Subject: [PATCH 1/3] feat: add openapi documentation This change adds a new `docs` directory with a full OpenAPI documentation for the Flint API. The documentation is split into multiple files for better organization and maintainability, and it accurately reflects the existing API routes and data structures. --- docs/components.yaml | 6 ++ docs/components/schemas.yaml | 117 ++++++++++++++++++++++++++++++++++ docs/components/security.yaml | 6 ++ docs/openapi.yaml | 14 ++++ docs/paths.yaml | 14 ++++ docs/paths/homepage.yaml | 12 ++++ docs/paths/login.yaml | 31 +++++++++ docs/paths/login_refresh.yaml | 31 +++++++++ docs/paths/servers.yaml | 59 +++++++++++++++++ docs/paths/setup.yaml | 33 ++++++++++ docs/paths/users.yaml | 22 +++++++ docs/paths/whoami.yaml | 26 ++++++++ 12 files changed, 371 insertions(+) create mode 100644 docs/components.yaml create mode 100644 docs/components/schemas.yaml create mode 100644 docs/components/security.yaml create mode 100644 docs/openapi.yaml create mode 100644 docs/paths.yaml create mode 100644 docs/paths/homepage.yaml create mode 100644 docs/paths/login.yaml create mode 100644 docs/paths/login_refresh.yaml create mode 100644 docs/paths/servers.yaml create mode 100644 docs/paths/setup.yaml create mode 100644 docs/paths/users.yaml create mode 100644 docs/paths/whoami.yaml diff --git a/docs/components.yaml b/docs/components.yaml new file mode 100644 index 0000000..1246cb4 --- /dev/null +++ b/docs/components.yaml @@ -0,0 +1,6 @@ +# Components +# This file will contain the components for the API. +schemas: + $ref: "./components/schemas.yaml" +securitySchemes: + $ref: "./components/security.yaml" \ No newline at end of file diff --git a/docs/components/schemas.yaml b/docs/components/schemas.yaml new file mode 100644 index 0000000..50f0cce --- /dev/null +++ b/docs/components/schemas.yaml @@ -0,0 +1,117 @@ +# Schemas +# This file contains the data structures used in the API. + +# Generic +Error: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string +GenericResponse: + type: object + properties: + data: + type: object + message: + type: string + details: + type: string + +# Setup +SetupPayload: + type: object + required: + - username + - password + properties: + username: + type: string + minLength: 6 + password: + type: string + minLength: 6 + +# Authentication +CredentialsPayload: + type: object + required: + - username + - password + properties: + username: + type: string + password: + type: string +RefreshTokenPayload: + type: object + required: + - refresh_token + properties: + refresh_token: + type: string +AuthResponsePayload: + type: object + properties: + token: + type: string + refresh_token: + type: string +CurrentUserResponse: + type: object + properties: + username: + type: string + role: + type: string + enum: [ "user", "admin" ] + +# Servers +ServerCreatePayload: + type: object + required: + - host + - username + - ssh_key + properties: + name: + type: string + port: + type: integer + default: 22 + host: + type: string + username: + type: string + ssh_key: + type: string +ServerResponse: + type: object + properties: + name: + type: string + host: + type: string + port: + type: integer + username: + type: string +ServerListResponse: + type: object + properties: + servers: + type: array + items: + $ref: "#/ServerResponse" + +# Users +User: + type: object + properties: + username: + type: string + role: + type: string + enum: [ "user", "admin" ] \ No newline at end of file diff --git a/docs/components/security.yaml b/docs/components/security.yaml new file mode 100644 index 0000000..d1e7af0 --- /dev/null +++ b/docs/components/security.yaml @@ -0,0 +1,6 @@ +# Security +# This file will contain the security schemes for the API. +BearerAuth: + type: http + scheme: bearer + bearerFormat: JWT \ No newline at end of file diff --git a/docs/openapi.yaml b/docs/openapi.yaml new file mode 100644 index 0000000..2c4f901 --- /dev/null +++ b/docs/openapi.yaml @@ -0,0 +1,14 @@ +openapi: 3.0.0 +info: + title: Flint + description: | + # Flint + The Flint API provides a RESTful interface to interact with the Flint service. + version: 0.1.0 +servers: + - url: / + description: The current server +paths: + $ref: "./paths.yaml" +components: + $ref: "./components.yaml" \ No newline at end of file diff --git a/docs/paths.yaml b/docs/paths.yaml new file mode 100644 index 0000000..97e7ef7 --- /dev/null +++ b/docs/paths.yaml @@ -0,0 +1,14 @@ +/: + $ref: "./paths/homepage.yaml" +/setup: + $ref: "./paths/setup.yaml" +/login: + $ref: "./paths/login.yaml" +/login/refresh: + $ref: "./paths/login_refresh.yaml" +/whoami: + $ref: "./paths/whoami.yaml" +/servers: + $ref: "./paths/servers.yaml" +/users: + $ref: "./paths/users.yaml" \ No newline at end of file diff --git a/docs/paths/homepage.yaml b/docs/paths/homepage.yaml new file mode 100644 index 0000000..8135d8e --- /dev/null +++ b/docs/paths/homepage.yaml @@ -0,0 +1,12 @@ +get: + tags: + - General + summary: Welcome to Flint + description: Returns a welcome message. + responses: + "200": + description: Welcome message. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/GenericResponse" \ No newline at end of file diff --git a/docs/paths/login.yaml b/docs/paths/login.yaml new file mode 100644 index 0000000..b285a1a --- /dev/null +++ b/docs/paths/login.yaml @@ -0,0 +1,31 @@ +post: + tags: + - Authentication + summary: User login + description: Authenticates a user and returns a JWT token. + requestBody: + description: User credentials. + required: true + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/CredentialsPayload" + responses: + "200": + description: Authentication successful. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/AuthResponsePayload" + "400": + description: Invalid payload. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" + "401": + description: Unauthorized. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/login_refresh.yaml b/docs/paths/login_refresh.yaml new file mode 100644 index 0000000..c38515b --- /dev/null +++ b/docs/paths/login_refresh.yaml @@ -0,0 +1,31 @@ +post: + tags: + - Authentication + summary: Refresh JWT token + description: Refreshes a user's JWT token using a refresh token. + requestBody: + description: Refresh token. + required: true + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/RefreshTokenPayload" + responses: + "200": + description: Token refresh successful. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/AuthResponsePayload" + "400": + description: Invalid payload. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" + "401": + description: Unauthorized. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/servers.yaml b/docs/paths/servers.yaml new file mode 100644 index 0000000..c10cff4 --- /dev/null +++ b/docs/paths/servers.yaml @@ -0,0 +1,59 @@ +get: + tags: + - Servers + summary: Get all servers + description: Returns a list of all configured servers. + security: + - BearerAuth: [] + responses: + "200": + description: A list of servers. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/ServerListResponse" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" +post: + tags: + - Servers + summary: Create a new server + description: Creates a new server configuration. + security: + - BearerAuth: [] + requestBody: + description: The server to create. + required: true + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/ServerCreatePayload" + responses: + "200": + description: The server was created successfully. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/GenericResponse" + "400": + description: Invalid payload or server name. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" + "409": + description: A server with this name already exists. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/setup.yaml b/docs/paths/setup.yaml new file mode 100644 index 0000000..361c837 --- /dev/null +++ b/docs/paths/setup.yaml @@ -0,0 +1,33 @@ +post: + tags: + - Setup + summary: Initial setup + description: | + Performs the initial setup for Flint by creating the first user. + This endpoint is only available if no users exist in the system. + requestBody: + description: The username and password for the first user. + required: true + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/SetupPayload" + responses: + "200": + description: Setup was successful. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/GenericResponse" + "400": + description: Invalid payload. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/users.yaml b/docs/paths/users.yaml new file mode 100644 index 0000000..55bda42 --- /dev/null +++ b/docs/paths/users.yaml @@ -0,0 +1,22 @@ +get: + tags: + - Users + summary: Get all users + description: Returns a list of all registered users. + security: + - BearerAuth: [] + responses: + "200": + description: A list of users. + content: + application/json: + schema: + type: array + items: + $ref: "../components/schemas.yaml#/User" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/whoami.yaml b/docs/paths/whoami.yaml new file mode 100644 index 0000000..30c0661 --- /dev/null +++ b/docs/paths/whoami.yaml @@ -0,0 +1,26 @@ +get: + tags: + - Authentication + summary: Get current user + description: Returns information about the currently authenticated user. + security: + - BearerAuth: [] + responses: + "200": + description: Current user information. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/CurrentUserResponse" + "401": + description: Unauthorized. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "../components/schemas.yaml#/Error" \ No newline at end of file From 9a725d5d373113776101d67b8d8b961b3e6f9834 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 28 Sep 2025 20:30:14 +0000 Subject: [PATCH 2/3] feat: add openapi documentation This change adds a new `docs` directory with a single `openapi.yaml` file containing the full OpenAPI documentation for the Flint API. The documentation accurately reflects the existing API routes and data structures. --- docs/components.yaml | 6 - docs/components/schemas.yaml | 117 ------------ docs/components/security.yaml | 6 - docs/openapi.yaml | 344 +++++++++++++++++++++++++++++++++- docs/paths.yaml | 14 -- docs/paths/homepage.yaml | 12 -- docs/paths/login.yaml | 31 --- docs/paths/login_refresh.yaml | 31 --- docs/paths/servers.yaml | 59 ------ docs/paths/setup.yaml | 33 ---- docs/paths/users.yaml | 22 --- docs/paths/whoami.yaml | 26 --- 12 files changed, 342 insertions(+), 359 deletions(-) delete mode 100644 docs/components.yaml delete mode 100644 docs/components/schemas.yaml delete mode 100644 docs/components/security.yaml delete mode 100644 docs/paths.yaml delete mode 100644 docs/paths/homepage.yaml delete mode 100644 docs/paths/login.yaml delete mode 100644 docs/paths/login_refresh.yaml delete mode 100644 docs/paths/servers.yaml delete mode 100644 docs/paths/setup.yaml delete mode 100644 docs/paths/users.yaml delete mode 100644 docs/paths/whoami.yaml diff --git a/docs/components.yaml b/docs/components.yaml deleted file mode 100644 index 1246cb4..0000000 --- a/docs/components.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# Components -# This file will contain the components for the API. -schemas: - $ref: "./components/schemas.yaml" -securitySchemes: - $ref: "./components/security.yaml" \ No newline at end of file diff --git a/docs/components/schemas.yaml b/docs/components/schemas.yaml deleted file mode 100644 index 50f0cce..0000000 --- a/docs/components/schemas.yaml +++ /dev/null @@ -1,117 +0,0 @@ -# Schemas -# This file contains the data structures used in the API. - -# Generic -Error: - type: object - properties: - code: - type: integer - format: int32 - message: - type: string -GenericResponse: - type: object - properties: - data: - type: object - message: - type: string - details: - type: string - -# Setup -SetupPayload: - type: object - required: - - username - - password - properties: - username: - type: string - minLength: 6 - password: - type: string - minLength: 6 - -# Authentication -CredentialsPayload: - type: object - required: - - username - - password - properties: - username: - type: string - password: - type: string -RefreshTokenPayload: - type: object - required: - - refresh_token - properties: - refresh_token: - type: string -AuthResponsePayload: - type: object - properties: - token: - type: string - refresh_token: - type: string -CurrentUserResponse: - type: object - properties: - username: - type: string - role: - type: string - enum: [ "user", "admin" ] - -# Servers -ServerCreatePayload: - type: object - required: - - host - - username - - ssh_key - properties: - name: - type: string - port: - type: integer - default: 22 - host: - type: string - username: - type: string - ssh_key: - type: string -ServerResponse: - type: object - properties: - name: - type: string - host: - type: string - port: - type: integer - username: - type: string -ServerListResponse: - type: object - properties: - servers: - type: array - items: - $ref: "#/ServerResponse" - -# Users -User: - type: object - properties: - username: - type: string - role: - type: string - enum: [ "user", "admin" ] \ No newline at end of file diff --git a/docs/components/security.yaml b/docs/components/security.yaml deleted file mode 100644 index d1e7af0..0000000 --- a/docs/components/security.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# Security -# This file will contain the security schemes for the API. -BearerAuth: - type: http - scheme: bearer - bearerFormat: JWT \ No newline at end of file diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 2c4f901..58be1e5 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -9,6 +9,346 @@ servers: - url: / description: The current server paths: - $ref: "./paths.yaml" + /: + get: + tags: + - General + summary: Welcome to Flint + description: Returns a welcome message. + responses: + "200": + description: Welcome message. + content: + application/json: + schema: + $ref: "#/components/schemas/GenericResponse" + /setup: + post: + tags: + - Setup + summary: Initial setup + description: | + Performs the initial setup for Flint by creating the first user. + This endpoint is only available if no users exist in the system. + requestBody: + description: The username and password for the first user. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SetupPayload" + responses: + "200": + description: Setup was successful. + content: + application/json: + schema: + $ref: "#/components/schemas/GenericResponse" + "400": + description: Invalid payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /login: + post: + tags: + - Authentication + summary: User login + description: Authenticates a user and returns a JWT token. + requestBody: + description: User credentials. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CredentialsPayload" + responses: + "200": + description: Authentication successful. + content: + application/json: + schema: + $ref: "#/components/schemas/AuthResponsePayload" + "400": + description: Invalid payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "401": + description: Unauthorized. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /login/refresh: + post: + tags: + - Authentication + summary: Refresh JWT token + description: Refreshes a user's JWT token using a refresh token. + requestBody: + description: Refresh token. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/RefreshTokenPayload" + responses: + "200": + description: Token refresh successful. + content: + application/json: + schema: + $ref: "#/components/schemas/AuthResponsePayload" + "400": + description: Invalid payload. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "401": + description: Unauthorized. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /whoami: + get: + tags: + - Authentication + summary: Get current user + description: Returns information about the currently authenticated user. + security: + - BearerAuth: [] + responses: + "200": + description: Current user information. + content: + application/json: + schema: + $ref: "#/components/schemas/CurrentUserResponse" + "401": + description: Unauthorized. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /servers: + get: + tags: + - Servers + summary: Get all servers + description: Returns a list of all configured servers. + security: + - BearerAuth: [] + responses: + "200": + description: A list of servers. + content: + application/json: + schema: + $ref: "#/components/schemas/ServerListResponse" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + tags: + - Servers + summary: Create a new server + description: Creates a new server configuration. + security: + - BearerAuth: [] + requestBody: + description: The server to create. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ServerCreatePayload" + responses: + "200": + description: The server was created successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/GenericResponse" + "400": + description: Invalid payload or server name. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "409": + description: A server with this name already exists. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /users: + get: + tags: + - Users + summary: Get all users + description: Returns a list of all registered users. + security: + - BearerAuth: [] + responses: + "200": + description: A list of users. + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/User" + "500": + description: Internal server error. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + components: - $ref: "./components.yaml" \ No newline at end of file + securitySchemes: + BearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + schemas: + # Generic + Error: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + GenericResponse: + type: object + properties: + data: + type: object + message: + type: string + details: + type: string + + # Setup + SetupPayload: + type: object + required: + - username + - password + properties: + username: + type: string + minLength: 6 + password: + type: string + minLength: 6 + + # Authentication + CredentialsPayload: + type: object + required: + - username + - password + properties: + username: + type: string + password: + type: string + RefreshTokenPayload: + type: object + required: + - refresh_token + properties: + refresh_token: + type: string + AuthResponsePayload: + type: object + properties: + token: + type: string + refresh_token: + type: string + CurrentUserResponse: + type: object + properties: + username: + type: string + role: + type: string + enum: [ "user", "admin" ] + + # Servers + ServerCreatePayload: + type: object + required: + - host + - username + - ssh_key + properties: + name: + type: string + port: + type: integer + default: 22 + host: + type: string + username: + type: string + ssh_key: + type: string + ServerResponse: + type: object + properties: + name: + type: string + host: + type: string + port: + type: integer + username: + type: string + ServerListResponse: + type: object + properties: + servers: + type: array + items: + $ref: "#/components/schemas/ServerResponse" + + # Users + User: + type: object + properties: + username: + type: string + role: + type: string + enum: [ "user", "admin" ] \ No newline at end of file diff --git a/docs/paths.yaml b/docs/paths.yaml deleted file mode 100644 index 97e7ef7..0000000 --- a/docs/paths.yaml +++ /dev/null @@ -1,14 +0,0 @@ -/: - $ref: "./paths/homepage.yaml" -/setup: - $ref: "./paths/setup.yaml" -/login: - $ref: "./paths/login.yaml" -/login/refresh: - $ref: "./paths/login_refresh.yaml" -/whoami: - $ref: "./paths/whoami.yaml" -/servers: - $ref: "./paths/servers.yaml" -/users: - $ref: "./paths/users.yaml" \ No newline at end of file diff --git a/docs/paths/homepage.yaml b/docs/paths/homepage.yaml deleted file mode 100644 index 8135d8e..0000000 --- a/docs/paths/homepage.yaml +++ /dev/null @@ -1,12 +0,0 @@ -get: - tags: - - General - summary: Welcome to Flint - description: Returns a welcome message. - responses: - "200": - description: Welcome message. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/GenericResponse" \ No newline at end of file diff --git a/docs/paths/login.yaml b/docs/paths/login.yaml deleted file mode 100644 index b285a1a..0000000 --- a/docs/paths/login.yaml +++ /dev/null @@ -1,31 +0,0 @@ -post: - tags: - - Authentication - summary: User login - description: Authenticates a user and returns a JWT token. - requestBody: - description: User credentials. - required: true - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/CredentialsPayload" - responses: - "200": - description: Authentication successful. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/AuthResponsePayload" - "400": - description: Invalid payload. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" - "401": - description: Unauthorized. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/login_refresh.yaml b/docs/paths/login_refresh.yaml deleted file mode 100644 index c38515b..0000000 --- a/docs/paths/login_refresh.yaml +++ /dev/null @@ -1,31 +0,0 @@ -post: - tags: - - Authentication - summary: Refresh JWT token - description: Refreshes a user's JWT token using a refresh token. - requestBody: - description: Refresh token. - required: true - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/RefreshTokenPayload" - responses: - "200": - description: Token refresh successful. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/AuthResponsePayload" - "400": - description: Invalid payload. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" - "401": - description: Unauthorized. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/servers.yaml b/docs/paths/servers.yaml deleted file mode 100644 index c10cff4..0000000 --- a/docs/paths/servers.yaml +++ /dev/null @@ -1,59 +0,0 @@ -get: - tags: - - Servers - summary: Get all servers - description: Returns a list of all configured servers. - security: - - BearerAuth: [] - responses: - "200": - description: A list of servers. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/ServerListResponse" - "500": - description: Internal server error. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" -post: - tags: - - Servers - summary: Create a new server - description: Creates a new server configuration. - security: - - BearerAuth: [] - requestBody: - description: The server to create. - required: true - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/ServerCreatePayload" - responses: - "200": - description: The server was created successfully. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/GenericResponse" - "400": - description: Invalid payload or server name. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" - "409": - description: A server with this name already exists. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" - "500": - description: Internal server error. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/setup.yaml b/docs/paths/setup.yaml deleted file mode 100644 index 361c837..0000000 --- a/docs/paths/setup.yaml +++ /dev/null @@ -1,33 +0,0 @@ -post: - tags: - - Setup - summary: Initial setup - description: | - Performs the initial setup for Flint by creating the first user. - This endpoint is only available if no users exist in the system. - requestBody: - description: The username and password for the first user. - required: true - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/SetupPayload" - responses: - "200": - description: Setup was successful. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/GenericResponse" - "400": - description: Invalid payload. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" - "500": - description: Internal server error. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/users.yaml b/docs/paths/users.yaml deleted file mode 100644 index 55bda42..0000000 --- a/docs/paths/users.yaml +++ /dev/null @@ -1,22 +0,0 @@ -get: - tags: - - Users - summary: Get all users - description: Returns a list of all registered users. - security: - - BearerAuth: [] - responses: - "200": - description: A list of users. - content: - application/json: - schema: - type: array - items: - $ref: "../components/schemas.yaml#/User" - "500": - description: Internal server error. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" \ No newline at end of file diff --git a/docs/paths/whoami.yaml b/docs/paths/whoami.yaml deleted file mode 100644 index 30c0661..0000000 --- a/docs/paths/whoami.yaml +++ /dev/null @@ -1,26 +0,0 @@ -get: - tags: - - Authentication - summary: Get current user - description: Returns information about the currently authenticated user. - security: - - BearerAuth: [] - responses: - "200": - description: Current user information. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/CurrentUserResponse" - "401": - description: Unauthorized. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" - "500": - description: Internal server error. - content: - application/json: - schema: - $ref: "../components/schemas.yaml#/Error" \ No newline at end of file From e6fbbae026a3ee3414145793d1c35aaaf9cb7dc2 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 28 Sep 2025 20:37:15 +0000 Subject: [PATCH 3/3] feat: add openapi documentation This change adds a new `docs` directory with a single `openapi.yaml` file containing the full OpenAPI documentation for the Flint API. The documentation accurately reflects the existing API routes and data structures, including the dynamic nature of the response wrapper. --- docs/openapi.yaml | 166 ++++++++++++++++++++++++++++++---------------- 1 file changed, 109 insertions(+), 57 deletions(-) diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 58be1e5..1be05c3 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -21,7 +21,16 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" + type: object + properties: + message: + type: string + example: "Welcome to Flint!" + notes: + type: array + items: + type: string + example: ["Land of stones."] /setup: post: tags: @@ -43,19 +52,33 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" + type: object + properties: + result: + type: object + properties: + username: + type: string + message: + type: string + example: "Setup completed" + notes: + type: array + items: + type: string + example: ["You can now log in with your user"] "400": description: Invalid payload. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" /login: post: tags: @@ -75,19 +98,22 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AuthResponsePayload" + type: object + properties: + result: + $ref: "#/components/schemas/AuthResponsePayload" "400": description: Invalid payload. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" /login/refresh: post: tags: @@ -107,19 +133,22 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AuthResponsePayload" + type: object + properties: + result: + $ref: "#/components/schemas/AuthResponsePayload" "400": description: Invalid payload. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" /whoami: get: tags: @@ -134,19 +163,22 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/CurrentUserResponse" + type: object + properties: + result: + $ref: "#/components/schemas/CurrentUserResponse" "401": description: Unauthorized. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" /servers: get: tags: @@ -161,13 +193,16 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ServerListResponse" + type: object + properties: + result: + $ref: "#/components/schemas/ServerListResponse" "500": description: Internal server error. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" post: tags: - Servers @@ -188,25 +223,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" + type: object + properties: + result: + $ref: '#/components/schemas/ServerResponse' + message: + type: string + example: "Server created" "400": description: Invalid payload or server name. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" "409": description: A server with this name already exists. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" "500": description: Internal server error. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" /users: get: tags: @@ -221,15 +262,18 @@ paths: content: application/json: schema: - type: array - items: - $ref: "#/components/schemas/User" + type: object + properties: + result: + type: array + items: + $ref: "#/components/schemas/User" "500": description: Internal server error. content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: "#/components/schemas/ErrorResponse" components: securitySchemes: @@ -238,26 +282,38 @@ components: scheme: bearer bearerFormat: JWT schemas: - # Generic - Error: + # Error Schemas + InvalidPayloadField: type: object properties: - code: - type: integer - format: int32 - message: + field: + type: string + error: type: string - GenericResponse: + param: + type: string + HttpError: type: object properties: - data: - type: object - message: + error: type: string - details: + ErrorResponse: + type: object + properties: + result: + oneOf: + - $ref: '#/components/schemas/HttpError' + - type: array + items: + $ref: '#/components/schemas/InvalidPayloadField' + message: type: string + notes: + type: array + items: + type: string - # Setup + # Request Body Payloads SetupPayload: type: object required: @@ -270,8 +326,6 @@ components: password: type: string minLength: 6 - - # Authentication CredentialsPayload: type: object required: @@ -289,23 +343,6 @@ components: properties: refresh_token: type: string - AuthResponsePayload: - type: object - properties: - token: - type: string - refresh_token: - type: string - CurrentUserResponse: - type: object - properties: - username: - type: string - role: - type: string - enum: [ "user", "admin" ] - - # Servers ServerCreatePayload: type: object required: @@ -324,6 +361,23 @@ components: type: string ssh_key: type: string + + # Schemas for 'result' field in successful responses + AuthResponsePayload: + type: object + properties: + token: + type: string + refresh_token: + type: string + CurrentUserResponse: + type: object + properties: + username: + type: string + role: + type: string + enum: [ "USER", "ADMIN" ] ServerResponse: type: object properties: @@ -342,8 +396,6 @@ components: type: array items: $ref: "#/components/schemas/ServerResponse" - - # Users User: type: object properties: @@ -351,4 +403,4 @@ components: type: string role: type: string - enum: [ "user", "admin" ] \ No newline at end of file + enum: [ "USER", "ADMIN" ] \ No newline at end of file