Smithy is a protocol-agnostic interface definition language and set of tools for generating clients, servers, and documentation for any programming language.
There appears to be a bug in the open-api plugin that leads to incorrectly applied documentation. This is causing some friction for us, requiring refactoring of our model to display documentation correctly. If the plugin behaved according to the documentation here: Effective documentation, we would not have any issue.
To repro:
model.smithy
$version: "2"
namespace example
use aws.api#service
use aws.protocols#restJson1
/// Cutting edge foo barring service, now with AI
@service(sdkId: "Foo")
@restJson1
service FooService {
version: "2006-03-01"
operations: [
BarOperation
]
}
/// Performs a bar operation.
@http(uri: "/bar", method: "POST")
operation BarOperation {
input: BarInput
output: BarOutput
}
@documentation("It's a Quux")
structure Quux {
quux: String
}
/// Input for the BarOperation.
structure BarInput {
@required
@documentation("It's a Bar")
bar: Quux
}
/// Output for the BarOperation.
structure BarOutput {
/// The result of the bar operation.
result: String
}
There appears to be a bug in the
open-api
plugin that leads to incorrectly applied documentation. This is causing some friction for us, requiring refactoring of our model to display documentation correctly. If the plugin behaved according to the documentation here: Effective documentation, we would not have any issue.To repro:
model.smithy
smithy-build.json
This produces a
model.json
that correctly contains"It's a Bar"
for the member's documentation:however, the generated
FooService.openapi.json
contains a schema that looks like this:I expect to see: