Gateway OpenAPI schema live documentation #614

neoxelox · 2024-11-14T13:46:53Z

What?

Implement OpenAPI + Swagger UI for Latitude gateway API endpoints

Issue

#499

TODO

Do prove of concept with /run api v2 ✅
Move evaluate tests to new folder 👈 I'm here
Consider if some schemas in core should go in gateway
Migrate all api routes to use OpenAPI interface
🔥 @hono/zod-validator

packages/core/src/constants.ts

andresgutgon · 2024-12-20T09:53:52Z

apps/gateway/src/routes/v1/chat/chat.handler.ts

+import { chainEventPresenter } from '$/common/documents/getData'
+
+// @ts-expect-error: streamSSE has type issues
+export const chatHandler: AppRouteHandler<ChatRoute> = async (c) => {


For some reason types are not working at this level. cc @neoxelox . Not only in SSE endpoints, in any of then. No big deal tho

mmm that's probably why I did what I did, handlers + route def altogether... this types are magical... but if c.req.valid does complain when getting unknown parameters from the request schema... I guess I am okay with that

andresgutgon · 2024-12-20T09:56:05Z

apps/gateway/src/routes/v2/documents/get/get.route.ts

+export const getRouteV2 = getRouteFactory({
+  path: ROUTES.v2.documents.get,
+  tags: ['Documents'],
+})


With this abstraction in place reusing routes is as easy as changing the path if the implementation didn't change

neoxelox · 2024-12-20T10:24:57Z

apps/gateway/src/openApi/configureOpenAPI.ts

+
+import { swaggerUI } from '@hono/swagger-ui'
+
+import packageJson from '../../package.json'


neoxelox · 2024-12-20T10:33:36Z

apps/gateway/src/openApi/createApp.ts

+import { OpenAPIHono } from '@hono/zod-openapi'
+
+export function createRouter() {
+  return new OpenAPIHono({ strict: false })


what does strict mean in there?

This https://hono.dev/docs/api/hono#strict-mode

neoxelox · 2024-12-20T10:36:00Z

apps/gateway/src/openApi/schemas/ai.ts

+})
+
+export const configSchema = z.object({}).passthrough()
+export const providerLogSchema = z.object({}).passthrough()


no schema for provider log?

It has not really been used in the API afaik

neoxelox · 2024-12-20T11:34:43Z

...gateway/src/routes/v2/conversations/createEvaluationResult/createEvaluationResult.handler.ts

@@ -122,3 +74,45 @@ async function validatedEvalConnectedToDocument({
    throw new BadRequestError('The evaluation is not connected to this prompt')
  }
 }
+
+// @ts-expect-error: streamSSE has type issues


is the type issue really because of streamSSE? I think it is because we are separating the handler from the magical createRoute, I would put that in the comment instead of streamSSE? (Also this handler does nothing about SSEs)

yeah there's no sse herem, why are we escaping the type checking?

neoxelox · 2024-12-20T11:37:34Z

apps/gateway/src/routes/v2/documents/get/get.handler.test.ts

@@ -18,7 +18,7 @@ describe('GET documents', () => {
  describe('unauthorized', () => {
    it('fails', async () => {
      const res = await app.request(
-        '/api/v1/projects/1/versions/asldkfjhsadl/documents/path/to/document',
+        '/api/v2/projects/1/versions/asldkfjhsadl/documents/path/to/document',


why the change from v1 to v2?

Before the implementation was in v1. So the test. Now I moved the implementation to v2, so the test

neoxelox

Buena currada refactorizando todo! The only thing I would say it to check out the comments saying "Types not working because of SSEs", I don't think its that. I think it is because we are separating the handler from the magical createRoute, I would put that in the comment instead?

geclos · 2024-12-20T14:12:56Z

apps/gateway/src/routes/app.ts

+app.route('/', v1Routes)
+app.route('/', documents)
+app.route('/', conversations)
+app.route('/', telemetry)


hmm this is very painful for the reader no? now there's no easy way to know what routes we are exposing you'd have to check every router

What I would have like is something similar to rails where routes.rb declares all the routes and routers are just the controllers with the handlers for each endpoint in that route

You can see all the routes in one place in routes.ts. Here are the paths

geclos · 2024-12-20T14:13:43Z

apps/gateway/src/routes/v2/conversations/chat/chat.handler.test.ts

@@ -118,7 +118,12 @@ describe('POST /chat', () => {
        messages: [
          {
            role: MessageRole.user,
-            content: 'fake-user-content',


hmm this should be valid content

Not according to this schema
https://github.com/latitude-dev/latitude-llm/blob/main/packages/core/src/constants.ts#L226-L243

This started failing now because before we did this "truquito"

import { messageSchema } from '@latitude-data/core/browser' const messagesSchema = z.array(z.any(messageSchema))

☝️ This is using any

What I did was remove the any

const messagesSchema = z.array(messageSchema)

And now types works!

geclos · 2024-12-20T14:16:30Z

apps/gateway/src/routes/v2/documents/logs/create.handler.ts

+import { CreateLogRoute } from '$/routes/v2/documents/logs/create.route'
+import { getData } from '$/common/documents/getData'
+
+// @ts-expect-error: broken types


i mean could we fix types 😅 it looks like this PR is breaking all types

Before we were not using openapi so no old types broken. Just this

AppRouteHandler<CreateLogRoute>

And is because it does a complex generic black magic. But types inside the handlers all work nicely

neoxelox added the 🚧 wip Work in progress label Nov 14, 2024

andresgutgon force-pushed the feature/499-automatic-gateway-api-docs branch 2 times, most recently from e2833ce to 3712dd3 Compare December 19, 2024 16:04

andresgutgon reviewed Dec 19, 2024

View reviewed changes

packages/core/src/constants.ts Outdated Show resolved Hide resolved

andresgutgon removed the 🚧 wip Work in progress label Dec 20, 2024

andresgutgon force-pushed the feature/499-automatic-gateway-api-docs branch from d355868 to ea138b3 Compare December 20, 2024 09:46

andresgutgon reviewed Dec 20, 2024

View reviewed changes

andresgutgon force-pushed the feature/499-automatic-gateway-api-docs branch from ea138b3 to acffc2c Compare December 20, 2024 10:00

OpenAPI zod Hono integration

c9ce2f8

andresgutgon force-pushed the feature/499-automatic-gateway-api-docs branch from acffc2c to c9ce2f8 Compare December 20, 2024 10:05

andresgutgon changed the title ~~Gateway OpenAPI schema~~ Gateway OpenAPI schema live documentation Dec 20, 2024

neoxelox commented Dec 20, 2024

View reviewed changes

geclos reviewed Dec 20, 2024

View reviewed changes

andresgutgon merged commit 3d0b277 into main Dec 20, 2024
3 checks passed

andresgutgon deleted the feature/499-automatic-gateway-api-docs branch December 20, 2024 14:42

github-actions bot locked and limited conversation to collaborators Dec 20, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Gateway OpenAPI schema live documentation #614

Gateway OpenAPI schema live documentation #614

neoxelox commented Nov 14, 2024 •

edited by andresgutgon

Loading

andresgutgon Dec 20, 2024 •

edited

Loading

neoxelox Dec 20, 2024

andresgutgon Dec 20, 2024

neoxelox Dec 20, 2024

neoxelox Dec 20, 2024

andresgutgon Dec 20, 2024

neoxelox Dec 20, 2024

andresgutgon Dec 20, 2024

neoxelox Dec 20, 2024

geclos Dec 20, 2024

neoxelox Dec 20, 2024

andresgutgon Dec 20, 2024

neoxelox left a comment

geclos Dec 20, 2024

geclos Dec 20, 2024

andresgutgon Dec 20, 2024

geclos Dec 20, 2024

andresgutgon Dec 20, 2024

geclos Dec 20, 2024

andresgutgon Dec 20, 2024


		import { swaggerUI } from '@hono/swagger-ui'

		import packageJson from '../../package.json'

Gateway OpenAPI schema live documentation #614

Gateway OpenAPI schema live documentation #614

Conversation

neoxelox commented Nov 14, 2024 • edited by andresgutgon Loading

What?

Issue

TODO

andresgutgon Dec 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neoxelox left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neoxelox commented Nov 14, 2024 •

edited by andresgutgon

Loading

andresgutgon Dec 20, 2024 •

edited

Loading