Repository: kubernetes
Issue: The generator for swagger docs removes some (but not all) of the line breaks, breaking the markdown
Labels: kind/bug,sig/api-machinery,triage/accepted

### What happened?

When generating the [networking/v1/types_swagger_doc_generated.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/api/networking/v1/types_swagger_doc_generated.go) from [networking/v1/types.go](https://github.com/kubernetes/api/blob/master/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](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/api/networking/v1/types.go#L461-L476):

```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](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/api/networking/v1/types_swagger_doc_generated.go#L33):

```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](https://github.com/kubernetes/website/blob/main/content/en/docs/reference/kubernetes-api/service-resources/ingress-v1.md?plain=1#L110-L122), this results in this:
```markdown
      - **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:
```markdown
      - **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](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/ingress-v1/#IngressSpec).

### Anything else we need to know?

This investigation was triggered by https://github.com/kubernetes/website/pull/35203 (which pointed me to "this is generated").