Sure, here's an example OpenAPI 3 specification for the endpoint you provided:
openapi: 3.0.0 info: version: 1.0.0 title: User API paths: /users/{id}: get: summary: Get user by ID operationId: getUserById tags: - Users parameters: - name: id in: path description: ID of the user to retrieve required: true schema: type: integer responses: '200': description: OK content: application/json: schema: type: object properties: id: type: integer example: 123 name: type: string example: Tom
This specification defines a GET operation on the /users/{id} endpoint, which takes a path parameter for the user ID and returns a JSON object with the user's ID and name. The response has a status code of 200 and a schema that defines the shape of the returned JSON object.
IMHO: 1. проще было бы заплатить несколько долларов в месяц и взять API от OpenAI, куда закинуть запросы по контроллерам которые преобразуют ваш код в готовое OpenAPI, если у вас проблема с генератором или можно наоборот сделать код по запросу с документацией. Да, тут есть некая проблема по завязыванию на определенное API, но зато даже бизнес-аналитики смогли бы что-то написать, если они у вас это фиксируют. 2. Если уже такая проблема что не получается с готовыми генераторами - написать свой, который транслирует простой запрос в OpenAPI. А то вы получили еще одну область ответственности, которой нужно учиться и которую нужно поддерживать, что мне кажется плохо.
Ахаха)) Спасибо, это очень остроумно — засунуть схему на языке JSight в OpenAI, мы до такого еще не догадались! Интересно, что OpenAI понял синтаксис языка JSight, даже не обучаясь — это уже само по себе говорит об интуитивной понятности JSight.
Что касается генерации схемы по примерам реальных запросов — идея интересная, и даже стоит у нас в планах. Однако на практике возникают практически нерешаемые трудности. В реальных проектах часто используются такие каверзные штуки, как пользовательские типы, наследование типов, вариативность типов (когда в одном и том же месте могуть быть данные либо одного типа, либо другого), специфические требования (например, регулярные выражения). Искусственный интеллект или любой другой алгоритм не сможет определить эти вещи просто по внешнему виду запросов.
Вот, например, у нас на бекенде JSight Server имеет API, при этом для описания всего лишь одного запроса используется 35 пользовательских типов данных: https://editor.jsight.io/r/4B01Gjo/1
Разве машина сможет определить все эти типы самостоятельно?
AI это, безусловно, очень современно. Но здесь вопрос в уровне доверия. Если рассматривать документацию как спецификацию, т.е. как контракт, то он должен быть точным. Использование кода бэкенда как исходника документации не гарантирует точности даже при использовании программных средств (во многих фреймворках есть такие фичи). С использованием AI проблем только прибавляется:
1. Как AI поймет реальные правила и ограничения данных из описания одного запроса? Предложенные готовые синтаксисы умеют описывать штучные запросы, но не схему данных.
2. Даже если сформулировать (что мы и сделали) или собрать из разных спецификаций синтаксис описания схемы и решить п.1, то как можно без редактуры использовать результат AI? Боюсь, что редактировать сочиненный ИИ OpenAPI еще больнее, чем писать его с нуля.
3. Как эту всю схему интегрировать в реальный рабочий процесс? Вот тут действительно возникнет очень специфичная новая область ответственности, которую нужно будет не то что поддерживать, а даже обслуживать.
Предложенная схема, конечно, может работать, но не ясно какую задачу она помогает решить.
"GET /users/{id}
200
{
"id" : 123,
"name": "Tom"
}"
Give me the OpenAPI 3 specification:
Sure, here's an example OpenAPI 3 specification for the endpoint you provided:
openapi: 3.0.0
info:
version: 1.0.0
title: User API
paths:
/users/{id}:
get:
summary: Get user by ID
operationId: getUserById
tags:
- Users
parameters:
- name: id
in: path
description: ID of the user to retrieve
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
type: integer
example: 123
name:
type: string
example: Tom
This specification defines a GET operation on the /users/{id} endpoint, which takes a path parameter for the user ID and returns a JSON object with the user's ID and name. The response has a status code of 200 and a schema that defines the shape of the returned JSON object.
IMHO:
1. проще было бы заплатить несколько долларов в месяц и взять API от OpenAI, куда закинуть запросы по контроллерам которые преобразуют ваш код в готовое OpenAPI, если у вас проблема с генератором или можно наоборот сделать код по запросу с документацией. Да, тут есть некая проблема по завязыванию на определенное API, но зато даже бизнес-аналитики смогли бы что-то написать, если они у вас это фиксируют.
2. Если уже такая проблема что не получается с готовыми генераторами - написать свой, который транслирует простой запрос в OpenAPI.
А то вы получили еще одну область ответственности, которой нужно учиться и которую нужно поддерживать, что мне кажется плохо.
Ну и синтаксисов для запросов куча, зачем свой не понятно.
https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html если у вас какой-то продукт intellij
https://hurl.dev/
ну и прочие.
Ахаха)) Спасибо, это очень остроумно — засунуть схему на языке JSight в OpenAI, мы до такого еще не догадались! Интересно, что OpenAI понял синтаксис языка JSight, даже не обучаясь — это уже само по себе говорит об интуитивной понятности JSight.
Что касается генерации схемы по примерам реальных запросов — идея интересная, и даже стоит у нас в планах. Однако на практике возникают практически нерешаемые трудности. В реальных проектах часто используются такие каверзные штуки, как пользовательские типы, наследование типов, вариативность типов (когда в одном и том же месте могуть быть данные либо одного типа, либо другого), специфические требования (например, регулярные выражения). Искусственный интеллект или любой другой алгоритм не сможет определить эти вещи просто по внешнему виду запросов.
Вот, например, у нас на бекенде JSight Server имеет API, при этом для описания всего лишь одного запроса используется 35 пользовательских типов данных: https://editor.jsight.io/r/4B01Gjo/1
Разве машина сможет определить все эти типы самостоятельно?
AI это, безусловно, очень современно. Но здесь вопрос в уровне доверия. Если рассматривать документацию как спецификацию, т.е. как контракт, то он должен быть точным. Использование кода бэкенда как исходника документации не гарантирует точности даже при использовании программных средств (во многих фреймворках есть такие фичи). С использованием AI проблем только прибавляется:
1. Как AI поймет реальные правила и ограничения данных из описания одного запроса? Предложенные готовые синтаксисы умеют описывать штучные запросы, но не схему данных.
2. Даже если сформулировать (что мы и сделали) или собрать из разных спецификаций синтаксис описания схемы и решить п.1, то как можно без редактуры использовать результат AI? Боюсь, что редактировать сочиненный ИИ OpenAPI еще больнее, чем писать его с нуля.
3. Как эту всю схему интегрировать в реальный рабочий процесс? Вот тут действительно возникнет очень специфичная новая область ответственности, которую нужно будет не то что поддерживать, а даже обслуживать.
Предложенная схема, конечно, может работать, но не ясно какую задачу она помогает решить.