The generator for swagger docs removes some (but not all) of the line breaks, breaking the markdown

[ePaul]

What happened?

When generating the networking/v1/types_swagger_doc_generated.go from networking/v1/types.go, some of the line breaks in the input documentation comments are removed (while others are kept).
From this we get https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json, which in turn is used to generate https://github.com/kubernetes/website/tree/main/content/en/docs/reference/kubernetes-api.
In the final documentation (e.g. https://kubernetes.io/docs/reference/kubernetes-api/service-resources/ingress-v1/#IngressSpec), the result is that list formatting is broken.

What did you expect to happen?

Line breaks in the input are kept for the Markdown processor. (Or the removal is at least smart enough to not remove relevant line breaks.)

How can we reproduce it (as minimally and precisely as possible)?

Input in types.go:

	// PathType determines the interpretation of the Path matching. PathType can
	// be one of the following values:
	// * Exact: Matches the URL path exactly.
	// * Prefix: Matches based on a URL path prefix split by '/'. Matching is
	//   done on a path element by element basis. A path element refers is the
	//   list of labels in the path split by the '/' separator. A request is a
	//   match for path p if every p is an element-wise prefix of p of the
	//   request path. Note that if the last element of the path is a substring
	//   of the last element in request path, it is not a match (e.g. /foo/bar
	//   matches /foo/bar/baz, but does not match /foo/barbaz).
	// * ImplementationSpecific: Interpretation of the Path matching is up to
	//   the IngressClass. Implementations can treat this as a separate PathType
	//   or treat it identically to Prefix or Exact path types.
	// Implementations are required to support all path types.
	PathType *PathType `json:"pathType" protobuf:"bytes,3,opt,name=pathType"`

This becomes in types_swagger_doc_generated.go:

var map_HTTPIngressPath = map[string]string{
	...,
	"pathType": "PathType determines the interpretation of the Path matching. PathType can be one of the following values: * Exact: Matches the URL path exactly. * Prefix: Matches based on a URL path prefix split by '/'. Matching is\n  done on a path element by element basis. A path element refers is the\n  list of labels in the path split by the '/' separator. A request is a\n  match for path p if every p is an element-wise prefix of p of the\n  request path. Note that if the last element of the path is a substring\n  of the last element in request path, it is not a match (e.g. /foo/bar\n  matches /foo/bar/baz, but does not match /foo/barbaz).\n* ImplementationSpecific: Interpretation of the Path matching is up to\n  the IngressClass. Implementations can treat this as a separate PathType\n  or treat it identically to Prefix or Exact path types.\nImplementations are required to support all path types.",
	...
}

We can here see that the first 3 line breaks are removed, the later ones are still there (escaped as \n).

In the generated markdown, ingress-v1.md, this results in this:

      - **rules.http.paths.pathType** (string), required

        PathType determines the interpretation of the Path matching. PathType can be one of the following values: * Exact: Matches the URL path exactly. * Prefix: Matches based on a URL path prefix split by '/'. Matching is
          done on a path element by element basis. A path element refers is the
          list of labels in the path split by the '/' separator. A request is a
          match for path p if every p is an element-wise prefix of p of the
          request path. Note that if the last element of the path is a substring
          of the last element in request path, it is not a match (e.g. /foo/bar
          matches /foo/bar/baz, but does not match /foo/barbaz).
        * ImplementationSpecific: Interpretation of the Path matching is up to
          the IngressClass. Implementations can treat this as a separate PathType
          or treat it identically to Prefix or Exact path types.
        Implementations are required to support all path types.

Instead, it should be this:

      - **rules.http.paths.pathType** (string), required

        PathType determines the interpretation of the Path matching. PathType can
        be one of the following values:
        * Exact: Matches the URL path exactly.
        * Prefix: Matches based on a URL path prefix split by '/'. Matching is
          done on a path element by element basis. A path element refers is the
          list of labels in the path split by the '/' separator. A request is a
          match for path p if every p is an element-wise prefix of p of the
          request path. Note that if the last element of the path is a substring
          of the last element in request path, it is not a match (e.g. /foo/bar
          matches /foo/bar/baz, but does not match /foo/barbaz).
        * ImplementationSpecific: Interpretation of the Path matching is up to
          the IngressClass. Implementations can treat this as a separate PathType
          or treat it identically to Prefix or Exact path types.
        Implementations are required to support all path types.

The same is happening for several other cases, this is just the one where I noticed it on the website.

Anything else we need to know?

This investigation was triggered by kubernetes/website#35203 (which pointed me to "this is generated").

[ePaul]

/sig api-machinery

[leilajal]

@ePaul thanks, are you going to send a PR for this?
/triage accepted

[ePaul]

Hi @leilajal, I didn't manage to find out where exactly this happens (my Go-knowledge is virtually nonexistent, I'm just a K8s user who stumbled over the broken documentation). If someone can point me to the file(s) I need to look at, I can take a stab (though likely not very soon), otherwise I'll have to leave this to people more experienced than me.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[vaibhav2107]

/remove-lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[vaibhav2107]

/remove-lifecycle stale

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

[ePaul]

The problem still exists as described.

There was a PR (#111505 by @haoruan), which somehow got lost and was auto-closed two days ago.

[alexzielenski]

/cc @Jefftree
since you reviewed #111505

[seans3]

/triage accepted