written by atjsh
- chatgpt can understand code
- chatgpt can generate json
- swagger documentations are written in json and spec are publicly accessable
which means, chatgpt can generate swagger documentation based on source code..?
i grabbed a simple API controller source code from github.
it's written in typescript.
import { Body, Controller, Get, Param, Post, UseGuards } from '@nestjs/common';
import { Roles } from '../common/decorators/roles.decorator';
import { RolesGuard } from '../common/guards/roles.guard';
import { ParseIntPipe } from '../common/pipes/parse-int.pipe';
import { CatsService } from './cats.service';
import { CreateCatDto } from './dto/create-cat.dto';
import { Cat } from './interfaces/cat.interface';
@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);
}
}and we use chatgpt to generate swagger documentation, from the source code.
- user input: the source code, as-is
- configuration
- temperature: 1.00
- max tokens: 32768
- top p: 1.00
- response: json_schema
the json schema used in the setup can be found in this github gist, 2_structured_output_json_schema.json. it's partial json schema of OpenAPI 3.0.
it did generate valid swagger documentation.
you can check the actual json generated by chatgpt in this github gist, 3_generated_swagger_1.json.
however, i did not included a payload information of HTTP body or "DTO"s. but as you can see, chatgpt just somehow generated these info.
i strongly suspect that the source code was already known by chatgpt.
Try yourself! you can reproduce this in OpenAI playground.
just turn on "Structured Output" mode, and set the schema with 2_structured_output_json_schema.json.
and chatgpt will generate swagger documentation for you.
NestJS, the framework used in this demo's source code already has support for automatic swagger generation. so why use chatgpt to generate swagger?
i think using chatgpt for api doc generation can be very useful when your source code has no such support. also, chatgpt is a powerful and unversal tool that can understand code.
if your source code is written in popular languages / framework / library, chatgpt will generate (almost) perfect api documentation for free.
you can do more extream documentation generation by including every source code of your API server and compressing them with prompt compressors, like LLMLingua-2 by Microsoft (i made one that runs in your browser) or simply bundling them with tools like esbuild (i tried it), and use it as LLM input.
That way, you might be able to generate complete API documentation. of course, you have to check for errors made by llm!
- OpenAI Strucutred Output guide
- Google Gemini Structured Output
- ollama Structured Outputs
- WebLLM Structured Generation - (WebLLM is in-browser LLM inference engine, similar to transformers.js)
- JSON Schema for OpenAPI 3.0
- Structured Output with Gemini Models: Begging, Threatening, and JSON-ing
- Structured outputs can hurt the performance of LLMs
i speak in Korean so there might be some grammer errors. hope you got the idea.