Include the user-provided operation description in the generated doc comment about swift-openapi-generator HOT 5 CLOSED

@JetForMe thanks for taking the time to file this issue.

I can confirm I can reproduce this.

Looking at our example package at Examples/GreetingService, we don't specify a description in the OpenAPI document—only on the parameter and the response:

...
paths:
  /greet:
    get:
      operationId: getGreeting
      parameters:
      - name: name
        required: false
        in: query
        description: A name used in the returned greeting.
        schema:
          type: string
      responses:
        '200':
          description: A success response with a greeting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Greeting'

When I build and take a look at the docs, here's what I see:

% swift build --package-path Examples/GreetingService/
...
Build complete! (154.18s)

% grep -C3 "func getGreeting" Examples/GreetingService/.build/plugins/outputs/greetingservice/GreetingServiceClient/OpenAPIGenerator/GeneratedSources/Types.swift
    /// Operation `getGreeting` performs `GET` on `/greet`
    ///
    /// - Remark: Generated from the `getGreeting` operation.
    func getGreeting(_ input: Operations.getGreeting.Input) async throws
        -> Operations.getGreeting.Output
}
/// Server URLs defined in the OpenAPI document.

If I add a description to the operation...

diff --git a/Examples/GreetingService/openapi.yaml b/Examples/GreetingService/openapi.yaml
index c670a49..f1cf5c5 100644
--- a/Examples/GreetingService/openapi.yaml
+++ b/Examples/GreetingService/openapi.yaml
@@ -9,6 +9,7 @@ paths:
   /greet:
     get:
       operationId: getGreeting
+      description: Gets a greeting.
       parameters:
       - name: name
         required: false

...and rebuild, I see no change to the generated documentation on func getGreeting(_:).

I think there's probably a few places where we haven't plumed through all the docs from the OpenAPI document, but we want to be doing that.

from swift-openapi-generator.

Just so I understand, are you saying the provided description Returns metadata about the API, including version. is not showing up in the generated documentation comment above the method?

The synthesized Operation getRoot performs GET on / should only be the last line of the comment, with the user-provided comment prepended to that.

If you're seeing something else, can you also provide the snippet of the generated code, please?

from swift-openapi-generator.

The comment isn't processed in any way, so what you put into the description field in YAML/JSON will get added to the comment. Theoretically you could use docc-specific syntax, but since the OpenAPI document is language-agnostic, I'd probably stick just to normal markdown syntax.

from swift-openapi-generator.

Thanks @simonjbeaumont, renamed accordingly.

from swift-openapi-generator.

That was fast, thanks! Do you think this works with a full-blown description written in DocC syntax?

from swift-openapi-generator.