OpenAPITools
[BUG] html2 generator: some schemas are generated empty
Bug Report Checklist
- [ ] Have you provided a full/minimal spec to reproduce the issue?
- [x] Have you validated the input using an OpenAPI validator (example)?
- [ ] Have you tested with the latest master to confirm the issue still exists?
- [x] Have you searched for related issues/PRs?
- [x] What's the actual output vs expected output?
Description
I'm trying to generate API docs for our API. I run html2 generator but it returns blank space where schemas should go.
openapi-generator version
5.3.1
OpenAPI declaration file content or url
I'm afraid I cannot provide the full API as it's covered by NDA. But here is a snippet for which schemas are not generated:
/inputs:
get:
summary: All inputs data
description: Returns a list of currently configured inputs
operationId: inputsGet
security:
- bearerAuth: []
tags:
- inputs
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Inputs'
'401':
$ref: '#/components/responses/Unauthorized'
default:
$ref: '#/components/responses/Error'
#...
Inputs:
type: array
items:
$ref: '#/components/schemas/Input'
Input:
type: object
required:
- input_id
- name
- config
- alerts_config
properties:
input_id:
type: integer
name:
type: string
# ...
It's just a regular API with paths and schemas. Nothing special.
It has perfectly generated code for more than 2 years. Recently we decided to generate docs using one of the html generators provided by this tool. GitLab renders the API using swagger w/o any problems.
Generation Details
We generate with html2 generator.
Steps to reproduce
The generator is launched with the following params:
$ npx openapi-generator-cli generate -i api_openapi.yaml -g html2 -o docs/api/
and it outputs empty schemas. Not all of them are empty, but most.
Is this issue only when using $ref to define the structures (i.e. if you inline them then it works)? If so, I've been seeing similar issues: https://github.com/OpenAPITools/openapi-generator/issues/11027
I have also run into this issue: the outer level of the schema is correctly generated, but the property schemas are not, even when I define them inline.
For the following response schema:
responses:
'200':
description: Details about the registration given by the ID parameter
content:
application/json:
schema:
type: object
properties:
meta:
type: object
items:
type: array
minItems: 1
maxItems: 1
items:
type: object
properties:
anInlineProperty:
type: string
anInlineObject:
type: object
properties:
id:
type: integer
name:
type: string
The html2 generator, with no customisation, produces the following:
Hi,
I iterated through all previous versions and found that this bug does not exists with version 5.4.0
So, a workaround for this bug is to issue following command in our terminal
openapi-generator-cli version-manager set 5.4.0
( I downgraded my version from 6.2.0 to 5.4.0 )
I can confirm this bug. Here is my reproducer:
{https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
"openapi": "3.0.1",
"info": {
"title": "Reproducer API for missing response schemas",
"version": "0.0.1"
},
"paths": {
"/appointments/{id}": {
"get": {
"summary": "test 1",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetAppointmentsResponse"
}
}
}
},
"400": {
"description": "client error, probably a wrong request"
},
"500": {
"description": "server error, probably a temporary problem"
}
}
}
}
},
"components": {
"schemas": {
"GetAppointmentsResponse": {
"type": "object",
"properties": {
"appointmentId": {
"type": "string"
}
}
}
}
}
}
openapi-generator-cli with html2 produces this:
This problem still exists even in latest nightly build: openapi-generator-cli-6.5.0-20230302.132003-21.jar
Here is a simple test file:
openapi: '3.0.3'
info:
title: 'Dummy'
version: 1.0.0
servers:
- url: https://dummy/v1
tags:
- name: DummyService
paths:
'/info/{inDummyParam}':
get:
tags:
- DummyService
summary: 'Retrieve data'
operationId: getDummy
parameters:
- $ref: '#/components/parameters/inDummyParam'
responses:
'200':
description: 'Successful operation'
content:
application/json:
schema:
$ref: '#/components/schemas/Ok2Dto'
'400':
description: 'Error'
content:
application/json:
schema:
type: string
components:
parameters:
inDummyParam:
name: inDummyParam
in: path
required: true
schema:
type: string
schemas:
Ok2Dto:
description: 'Data set for information on a specific loading unit.'
type: object
required:
- prop1
- prop2
properties:
prop1:
type: string
description: Unique ID
prop2:
type: string
description: Something else
Tested with latest nightly build version:
java -jar openapi-generator-cli-6.5.0-20230302.132003-21.jar generate -g html2 -i test.yaml -o htmlNightly
results in incorrect "Responses":
Tested with old 6.1.0 version:
java -jar openapi-generator-cli-6.1.0.jar generate -g html2 -i test.yaml -o html61
results in correct output:
I can confirm that in version 6.2.0 it is already broken. So somewhere between 6.1.0 and 6.2.0 the bug was introduced.
