OpenAPITools / OpenAPITools/openapi-generator
[BUG] API class descriptions / tag descriptions are not rendering
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Bug Report Checklist
- Have you provided a full/minimal spec to reproduce the issue?
- Have you validated the input using an OpenAPI validator (example)?
- Have you tested with the latest master to confirm the issue still exists?
- Have you searched for related issues/PRs?
- What's the actual output vs expected output?
- [Optional] Sponsorship to speed up the bug fix or feature request (example)
Description
API class descriptions / tag descriptions are rendering as empty.
Take the official PHP template, which includes a class-level {{#description}} for its APIDoc template:
# {{invokerPackage}}\{{classname}}{{#description}}
{{.}}{{/description}}
All URIs are relative to {{basePath}}, except if the operation defines another base path.
{{#description}} always renders empty, despite having tag descriptions in the OpenAPI Spec.
openapi-generator version
6.2.1
OpenAPI declaration file content or URL
Use the official PetStore API Spec, which includes these tag descriptions:
openapi: 3.0.0
tags:
- name: pet
description: Everything about your Pets
- name: store
description: Access to Petstore orders
- name: user
description: Operations about user
Generation Details
Generate a PHP client:
openapi-generator-cli generate -g php \
-i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
-o temp-php-client
See the generated result (docs/Api/PetApi.md):
# OpenAPI\Client\PetApi
All URIs are relative to http://petstore.swagger.io/v2, except if the operation defines another base path.
See the template (official PHP template):
# {{invokerPackage}}\{{classname}}{{#description}}
{{.}}{{/description}}
All URIs are relative to {{basePath}}, except if the operation defines another base path.
Notice how the PHP generator seems to support an API class-level description, yet doesn't render it (at least from the tag description... I'm not sure where else it would be reading this from?). I have a feeling many of the other generators exhibit this same behaviour (i.e. have a API class-level description but without any way of rendering content into it from the spec).
Steps to reproduce
See Generation Details (above).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with modules/openapi-generator/src/main/resources/php/api_doc.mustache and the official petstore.yaml spec. Generate the PHP client using the documented command and compare the tag descriptions with docs/Api/PetApi.md. Done means the API class or tag descriptions appear in the generated documentation as expected.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, php
- Domain
- api, documentation, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100