Skip to content

Instantly share code, notes, and snippets.

@atjsh

atjsh/1_README.md

Last active July 13, 2025 12:15
Show Gist options
  • Save atjsh/eed3a099cda279e55b0523237ca8010d to your computer and use it in GitHub Desktop.
Save atjsh/eed3a099cda279e55b0523237ca8010d to your computer and use it in GitHub Desktop.
Download ZIP
Gemini for Swagger Generation? (failed attempt)
Raw
1_README.md

i tried to use google gemini to generate OpenAPI Swagger doc, by providing structured output option as in JSON Schema spec of OpenAPI 3.0.

but it mostly failed with this error.

ApiError: {"error":{"code":400,"message":"The specified schema produces a constraint that has too many states for serving. Typical causes of this error are schemas with lots of text (for example, very long property or enum names), schemas with long array length limits (especially when nested), or schemas using complex value matchers (for example, integers or numbers with minimum/maximum bounds or strings with complex formats like date-time)","status":"INVALID_ARGUMENT"}}

and when i managed to made it work, the "Operation" definitions are mostly missing.

i share my attempts in hope that somebody might be able to fix this..

you can check my successful attempt with chatgpt.

Raw
2_gemini_json_schema_my_trials.js
const responseJsonSchema = {
"type": "object",
"required": [
"openapi",
"info",
"paths",
"components"
],
"properties": {
"openapi": {
"description": "@pattern ^3\\.0\\.\\d(-.+)?$",
"type": "string"
},
"info": {
"$ref": "#/$defs/Info"
},
"externalDocs": {
"$ref": "#/$defs/ExternalDocumentation"
},
"servers": {
"type": "array",
"items": {
"$ref": "#/$defs/Server"
}
},
"security": {
"type": "array",
"items": {
"$ref": "#/$defs/SecurityRequirement"
}
},
"tags": {
"description": "@uniqueItems",
"type": "array",
"items": {
"$ref": "#/$defs/Tag"
}
},
"paths": {
"$ref": "#/$defs/Paths"
},
"components": {
"$ref": "#/$defs/Components"
}
},
"$defs": {
"Info": {
"type": "object",
"required": [
"title",
"version"
],
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"termsOfService": {
"description": "@format uri-reference",
"type": "string"
},
"contact": {
"$ref": "#/$defs/Contact"
},
"license": {
"$ref": "#/$defs/License"
},
"version": {
"type": "string"
}
}
},
"Contact": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"description": "@format uri-reference",
"type": "string"
},
"email": {
"description": "@format email",
"type": "string"
}
},
"required": []
},
"License": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"url": {
"description": "@format uri-reference",
"type": "string"
}
}
},
"ExternalDocumentation": {
"type": "object",
"required": [
"url"
],
"properties": {
"description": {
"type": "string"
},
"url": {
"description": "@format uri-reference",
"type": "string"
}
}
},
"Server": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
},
"description": {
"type": "string"
},
"variables": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/ServerVariable"
},
"properties": {},
"required": []
}
}
},
"ServerVariable": {
"type": "object",
"required": [
"default"
],
"properties": {
"enum": {
"type": "array",
"items": {
"type": "string"
}
},
"default": {
"type": "string"
},
"description": {
"type": "string"
}
}
},
"SecurityRequirement": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"properties": {},
"required": []
},
"Tag": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"externalDocs": {
"$ref": "#/$defs/ExternalDocumentation"
}
}
},
"Paths": {
"type": "object",
"description": "Path as key and PathItem as value",
"additionalProperties": {
"$ref": "#/$defs/PathItem"
},
"properties": {},
"required": []
},
"PathItem": {
"type": "object",
"description": "PathItem describes the operations available on a single path. Methods as additional properties.",
"additionalProperties": {
"$ref": "#/$defs/Operation"
},
"properties": {
"$ref": {
"type": "string"
},
"summary": {
"type": "string"
},
"description": {
"type": "string"
},
// "operations": {
// "type": "array",
// "items": {
// "type": "object",
// "properties": {
// "method": {
// "type": "string",
// "description": "HTTP method of the operation (e.g., 'get', 'post', etc.)"
// },
// "operation": {
// // "$ref": "#/$defs/Operation"
// }
// }
// }
// },
// "get": {
// "$ref": "#/$defs/Operation"
// },
// "put": {
// "$ref": "#/$defs/Operation"
// },
// "post": {
// "$ref": "#/$defs/Operation"
// },
// "delete": {
// "$ref": "#/$defs/Operation"
// },
// "options": {
// "$ref": "#/$defs/Operation"
// },
// "head": {
// "$ref": "#/$defs/Operation"
// },
// "patch": {
// "$ref": "#/$defs/Operation"
// },
// "trace": {
// "$ref": "#/$defs/Operation"
// },
"servers": {
"type": "array",
"items": {
"$ref": "#/$defs/Server"
}
},
"parameters": {
"description": "@uniqueItems",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/$defs/Parameter"
},
{
"$ref": "#/$defs/Reference"
}
]
}
}
},
"required": []
},
"Operation": {
"type": "object",
"description": "Operation describes a single API operation on a path.",
"required": [
"responses"
],
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"summary": {
"type": "string"
},
"description": {
"type": "string"
},
"externalDocs": {
"$ref": "#/$defs/ExternalDocumentation"
},
"operationId": {
"type": "string"
},
"parameters": {
"description": "@uniqueItems",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/$defs/Parameter"
},
{
"$ref": "#/$defs/Reference"
}
]
}
},
"requestBody": {
"anyOf": [
{
"$ref": "#/$defs/RequestBody"
},
{
"$ref": "#/$defs/Reference"
}
]
},
"responses": {
"$ref": "#/$defs/Responses"
},
"callbacks": {
"type": "object",
"description": "Reference to Callback",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"deprecated": {
"type": "boolean"
},
"security": {
"type": "array",
"items": {
"$ref": "#/$defs/SecurityRequirement"
}
},
"servers": {
"type": "array",
"items": {
"$ref": "#/$defs/Server"
}
}
}
},
"Parameter": {
"anyOf": [
{
"$ref": "#/$defs/PathParameter"
},
{
"$ref": "#/$defs/QueryParameter"
},
{
"$ref": "#/$defs/HeaderParameter"
},
{
"$ref": "#/$defs/CookieParameter"
}
]
},
"PathParameter": {
"description": "Parameter in path"
},
"QueryParameter": {
"description": "Parameter in query"
},
"HeaderParameter": {
"description": "Parameter in header"
},
"CookieParameter": {
"description": "Parameter in cookie"
},
"Reference": {
"description": "Reference to other components. The reference must be a valid URI reference.",
"type": "object",
"required": [
"$ref"
],
"additionalProperties": {
"description": "@format uri-reference",
"type": "string"
},
"properties": {
"$ref": {
"description": "@format uri-reference",
"type": "string"
}
}
},
"RequestBody": {
"type": "object",
"required": [
"content"
],
"properties": {
"description": {
"type": "string"
},
"content": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/MediaType"
},
"properties": {},
"required": []
},
"required": {
"type": "boolean"
}
}
},
// "MediaType": {
// "$ref": "#/$defs/ExampleXORExamples"
// },
"MediaType": {
"type": "object",
"properties": {
"schema": {
"description": "Reference to Schema",
"oneOf": [
{
"$ref": "#/$defs/Schema"
},
{
"$ref": "#/$defs/Reference"
}
]
},
"example": {},
"examples": {
"type": "object",
"additionalProperties": {
"description": "Reference to Example",
"oneOf": [
// {
// "$ref": "#/$defs/Example"
// },
{
"$ref": "#/$defs/Reference"
}
]
}
},
// "encoding": {
// "type": "object",
// "additionalProperties": {
// "$ref": "#/$defs/Encoding"
// }
// }
},
// "allOf": [
// {
// "$ref": "#/$defs/ExampleXORExamples"
// }
// ]
},
// "ExampleXORExamples": {
// "description": "Example and examples are mutually exclusive"
// },
"Responses": {
"type": "object",
"properties": {
"default": {
"anyOf": [
{
"$ref": "#/$defs/Response"
},
{
"$ref": "#/$defs/Reference"
}
]
}
},
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Response"
},
{
"$ref": "#/$defs/Reference"
}
]
},
"minProperties": 1,
"required": []
},
"Response": {
"type": "object",
"required": [
"description"
],
"properties": {
"description": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Header"
},
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"content": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/MediaType"
},
"properties": {},
"required": []
},
"links": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Link"
},
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
}
}
},
"Header": {},
"Link": {
"type": "object",
"properties": {
"operationId": {
"type": "string"
},
"operationRef": {
"description": "@format uri-reference",
"type": "string"
},
"parameters": {
"type": "object",
"additionalProperties": {},
"properties": {},
"required": []
},
"requestBody": {},
"description": {
"type": "string"
},
"server": {
"$ref": "#/$defs/Server"
}
},
"not": {
"description": "Operation Id and Operation Ref are mutually exclusive",
"required": [
"operationId",
"operationRef"
]
},
"required": []
},
"Callback": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/PathItem"
},
"properties": {},
"required": []
},
"Components": {
"type": "object",
"properties": {
"schemas": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Schema"
},
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"responses": {
"type": "object",
"description": "Reference to Response",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"parameters": {
"type": "object",
"description": "Reference to Parameter",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"examples": {
"type": "object",
"description": "Reference to Example",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"requestBodies": {
"type": "object",
"description": "Reference to RequestBody",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"headers": {
"type": "object",
"description": "Reference to Header",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"securitySchemes": {
"type": "object",
"description": "Reference to SecurityScheme",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"links": {
"type": "object",
"description": "Reference to Link",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"callbacks": {
"type": "object",
"description": "Reference to Callback",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
}
},
"required": []
},
"Schema": {
"type": "object",
"description": "Schema can be used in various places, such as request body, response body, parameter, etc.",
"properties": {
"title": {
"type": "string"
},
"multipleOf": {
"description": "@exclusiveMinimum 0",
"type": "number"
},
"maximum": {
"type": "number"
},
"exclusiveMaximum": {
"type": "boolean"
},
"minimum": {
"type": "number"
},
"exclusiveMinimum": {
"type": "boolean"
},
"maxLength": {
"description": "@minimum 0",
"type": "integer"
},
"minLength": {
"description": "@minimum 0",
"type": "integer"
},
"pattern": {
"description": "@format regex",
"type": "string"
},
"maxItems": {
"description": "@minimum 0",
"type": "integer"
},
"minItems": {
"description": "@minimum 0",
"type": "integer"
},
"uniqueItems": {
"type": "boolean"
},
"maxProperties": {
"description": "@minimum 0",
"type": "integer"
},
"minProperties": {
"description": "@minimum 0",
"type": "integer"
},
"required": {
"description": "@minItems 1\n@uniqueItems",
"type": "array",
"items": {
"type": "string"
}
},
"enum": {
"description": "@minItems 1",
"type": "array",
"items": {}
},
"type": {},
"not": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"allOf": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
}
},
"oneOf": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
}
},
"anyOf": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
}
},
"items": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {
"type": "object",
"description": "A free form object that can contain any properties. The keys are property names, and the values are the property definitions.",
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
}
]
},
"properties": {},
"required": []
},
"additionalProperties": {
"anyOf": [
{
"$ref": "#/$defs/Reference"
},
{
"type": "boolean"
}
]
},
"description": {
"type": "string"
},
"format": {
"type": "string"
},
"default": {},
"nullable": {
"type": "boolean"
},
"discriminator": {
"$ref": "#/$defs/Discriminator"
},
"readOnly": {
"type": "boolean"
},
"writeOnly": {
"type": "boolean"
},
"example": {},
"externalDocs": {
"$ref": "#/$defs/ExternalDocumentation"
},
"deprecated": {
"type": "boolean"
},
"xml": {
"$ref": "#/$defs/XML"
}
},
"required": []
},
"Discriminator": {
"type": "object",
"required": [
"propertyName"
],
"properties": {
"propertyName": {
"type": "string"
},
"mapping": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"properties": {},
"required": []
}
}
},
"XML": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"namespace": {
"description": "@format uri",
"type": "string"
},
"prefix": {
"type": "string"
},
"attribute": {
"type": "boolean"
},
"wrapped": {
"type": "boolean"
}
},
"required": []
},
"Example": {
"type": "object",
"properties": {
"summary": {
"type": "string"
},
"description": {
"type": "string"
},
"value": {},
"externalValue": {
"description": "@format uri-reference",
"type": "string"
}
},
"required": []
},
"SecurityScheme": {
"anyOf": [
{
"$ref": "#/$defs/APIKeySecurityScheme"
},
{
"$ref": "#/$defs/HTTPSecurityScheme"
},
{
"$ref": "#/$defs/OAuth2SecurityScheme"
},
{
"$ref": "#/$defs/OpenIdConnectSecurityScheme"
}
]
},
"APIKeySecurityScheme": {
"type": "object",
"required": [
"type",
"name",
"in"
],
"properties": {
"type": {},
"name": {
"type": "string"
},
"in": {},
"description": {
"type": "string"
}
}
},
"HTTPSecurityScheme": {},
"OAuth2SecurityScheme": {
"type": "object",
"required": [
"type",
"flows"
],
"properties": {
"type": {},
"flows": {
"$ref": "#/$defs/OAuthFlows"
},
"description": {
"type": "string"
}
}
},
"OAuthFlows": {
"type": "object",
"properties": {
"implicit": {
"$ref": "#/$defs/ImplicitOAuthFlow"
},
"password": {
"$ref": "#/$defs/PasswordOAuthFlow"
},
"clientCredentials": {
"$ref": "#/$defs/ClientCredentialsFlow"
},
"authorizationCode": {
"$ref": "#/$defs/AuthorizationCodeOAuthFlow"
}
},
"required": []
},
"ImplicitOAuthFlow": {
"type": "object",
"required": [
"authorizationUrl",
"scopes"
],
"properties": {
"authorizationUrl": {
"description": "@format uri-reference",
"type": "string"
},
"refreshUrl": {
"description": "@format uri-reference",
"type": "string"
},
"scopes": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"properties": {},
"required": []
}
}
},
"PasswordOAuthFlow": {
"type": "object",
"required": [
"tokenUrl",
"scopes"
],
"properties": {
"tokenUrl": {
"description": "@format uri-reference",
"type": "string"
},
"refreshUrl": {
"description": "@format uri-reference",
"type": "string"
},
"scopes": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"properties": {},
"required": []
}
}
},
"ClientCredentialsFlow": {
"type": "object",
"required": [
"tokenUrl",
"scopes"
],
"properties": {
"tokenUrl": {
"description": "@format uri-reference",
"type": "string"
},
"refreshUrl": {
"description": "@format uri-reference",
"type": "string"
},
"scopes": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"properties": {},
"required": []
}
}
},
"AuthorizationCodeOAuthFlow": {
"type": "object",
"required": [
"authorizationUrl",
"tokenUrl",
"scopes"
],
"properties": {
"authorizationUrl": {
"description": "@format uri-reference",
"type": "string"
},
"tokenUrl": {
"description": "@format uri-reference",
"type": "string"
},
"refreshUrl": {
"description": "@format uri-reference",
"type": "string"
},
"scopes": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"properties": {},
"required": []
}
}
},
"OpenIdConnectSecurityScheme": {
"type": "object",
"required": [
"type",
"openIdConnectUrl"
],
"properties": {
"type": {},
"openIdConnectUrl": {
"description": "@format uri-reference",
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
const contents = `
\`\`\`typescript
import { IsInt, IsString } from 'class-validator';
import { Body, Controller, Get, Param, Post, UseGuards, Injectable } from '@nestjs/common';
export class CreateCatDto {
@IsString()
readonly name: string;
@IsInt()
readonly age: number;
@IsString()
readonly breed: string;
}
export interface Cat {
name: string;
age: number;
breed: string;
}
@Injectable()
export class CatsService {
private readonly cats: Cat[] = [];
create(cat: Cat) {
this.cats.push(cat);
}
findAll(): Promise<Cat[]> {
return Promise.resolve(this.cats);
}
}
@UseGuards(RolesGuard)
@Controller('cats')
export class CatsController {
constructor(private readonly catsService: CatsService) {}
@Post()
@Roles(['admin'])
async create(@Body() createCatDto: CreateCatDto) {
this.catsService.create(createCatDto);
}
@Get()
async findAll(): Promise<Cat[]> {
return this.catsService.findAll();
}
@Get(':id')
findOne(
@Param('id', new ParseIntPipe())
id: number,
) {
// Retrieve a Cat instance by ID
console.log(id);
}
}
\`\`\`
Generate the OpenAPI 3.0 schema for the above code snippet. Always include method name and operation.
`
import { GoogleGenAI } from '@google/genai'
const ai = new GoogleGenAI({
apiKey: platform.env.GOOGLE_GENAI_API_KEY,
});
async function main() {
const response = await ai.models.generateContent({
// model: "gemini-2.5-flash-lite-preview-06-17",
model: "gemini-2.5-pro",
contents,
config: {
responseJsonSchema,
responseMimeType: "application/json",
systemInstruction: "You are a helpful assistant that generates JSON schema for provided code snippets. The schema should be in OpenAPI 3.0 format. First, Generate the schema definitions as many as possible.",
}
});
console.log(response.text);
}
main();
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment