Description and Example for Parameters/Response

[VaslD]

How do I add both descriptions (arbitrary text) and examples (some value used as try-it-out preset) to path/body parameters and corresponding response?

Basically I'm looking for something like this (hacked generated webpage with HTML editor):

I'm calling .openAPI() like this:

.openAPI(
  summary: "...",
  path: ["id": "1234567890"],
  response: "AbCdeF",
  responseType: .text(.plain)
)

I guess description and example for HTTP-200 may go into errorResponses and errorDescriptions, that still leaves query, path, and body undocumented.

[dankinsoid]

@VaslD Hello!
I tried to minimize the code required for the documentation, so I didn’t include some features, including a description for individual fields or objects.
But it’s easy for me to add such functionality since it is in demand.
Let's think about the best way to do this.
Some ideas:

1. It could be some property wrapper in your object

@OpenAPIDescription("Identifier") 
public var id: String

2. Some additional parameters in openAPI method

.openAPI(
   path: PathParamters.self,
   descriptions: .path("id", "Identifier")
)

3. Some codegen tools to use native /// Identifier directives

If you don't want to wait for the library update you can use .openAPI(custom:) func after main openAPI

.openAPI(custom: \.parameters) {
    $0?.append(
        .value(
              ParameterObject(
                    name: "id",
                    in: .path,
                    description: "Identifier",
                    required: true, // required for all path params
                    schema: .string,
                    example: .string("example")
             )
        )
    )
}

[VaslD]

So since this is \.parameters, I guess I can have multiple .openAPI() on the same route? And how do they collide in case there are conflicts?

[dankinsoid]

@VaslD
Hello!
I implemented custom descriptions support in 3.14.0
Example of usage:

struct LoginParamters: Codable, OpenAPIDescriptable {

    let username: String
    let password: String

    static var openAPIDescription: OpenAPIDescriptionType? {
        OpenAPIDescription<CodingKeys>()
            .add(for: .username, "Username")
            .add(for: .password, "Password")
    }
}

[VaslD]

Sorry, was busy last week. This is awesome.