swagger-api / swagger-api/swagger-codegen

[elixir] Explicitly set @moduledoc false when empty

Open
#12,295 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Mustache
Stars
17.8k
Forks
6k
PR merge metrics
No merged PRs in 30d

Description

note: after learning a bit more about the structure of this repo and the 3.0.0 branch, I'll edit the issue to reflect the required changes in a day or two, apologies for the confusion

Description

For generated models, if a description is not present - moduledoc is set to empty string.
As per style guide, when moduledoc is empty, explicitly set the module doc value to false.

style guide reference: https://github.com/christopheradams/elixir_style_guide#moduledoc-false

Swagger-codegen version

All versions. Pinning to issue creation date, 3.0.51.

Swagger declaration file content or url
openapi: 3.0.1
info:
  title: elixir-moduledoc
  version: 1.0.0
servers:
  - url: /
paths:
  /foo:
    get:
      operationId: foo
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  bar:
                    type: string
Command line used for generation

Using the docker variant, but with language elixir and default options, would be able to replicate the issue.

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
    -i ./spec.yml \
    -g elixir
Steps to reproduce

Generate elixir client as shown above, produces a model file

# NOTE: This file is auto generated by OpenAPI Generator 7.0.1-SNAPSHOT (https://openapi-generator.tech).
# Do not edit this file manually.

defmodule ElixirModuledoc.Model.Foo200Response do
  @moduledoc """
  
  """

  @derive Jason.Encoder
  defstruct [
    :bar
  ]

  @type t :: %__MODULE__{
    :bar => String.t | nil
  }

  def decode(value) do
    value
  end
end

Related issues/PRs

N/A

Suggest a fix/enhancement

fix: add a condition to the moustache template for moduledoc

Expected generated file
# NOTE: This file is auto generated by OpenAPI Generator 7.0.1-SNAPSHOT (https://openapi-generator.tech).
# Do not edit this file manually.

defmodule ElixirModuledoc.Model.Foo200Response do
  @moduledoc false

  @derive Jason.Encoder
  defstruct [
    :bar
  ]

  @type t :: %__MODULE__{
    :bar => String.t | nil
  }

  def decode(value) do
    value
  end
end

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

Find the Elixir model Mustache template that emits @moduledoc and compare its empty-description path with the generated Foo200Response example. Reproduce the issue with the supplied OpenAPI YAML and Docker command, then verify that generated models use @moduledoc false when no description is present; check the 3.0.0 branch context before editing.

Written by the indexing model from the issue text.

Assessment

Tech stack
elixir, openapi
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.