OpenAPITools / OpenAPITools/openapi-generator

[BUG] API class descriptions / tag descriptions are not rendering

Open
#14,395 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.