Re: Swashbuckle documentation

[Greg Keogh]

I'm sure many of you will agree that the best way to solve a problem is to
go away and come back later (or asking the cat sometimes works). Just
before I sat down this morning I suddenly realised why my body parameters
were missing from the Swagger documentation output.

My IOperationFilter which adds the headers to the Parameter list was
*replacing* the collection, not *adding* to it if wasn't null.

Among the jumbled mix of samples, this one
<https://docs.microsoft.com/en-us/azure/app-service-api/app-service-api-dotnet-swashbuckle-customize>
correctly null checks the property.

I think this is a testament to just how sprawling .NET development is
becoming. We have so many patterns, frameworks, tools and components that
we have too much of a good thing. Many of them come from individuals or the
open community, and they wax and wane in popularity, and the documentation
is often sparse. When I have a specific development need these days I
naturally run web searches, but I find I'm spending more time searching and
searching and searching ... because I find hundreds of arguments, opinions,
competing products, confusing or conflicting samples, poor documentation,
sneaky dependencies and "magic" behaviour (which I hate most). Part of the
skill of being a modern developer is being a "living filter" to find what
you need.

*Greg K*

On 27 June 2017 at 17:02, Grant Castner <gcast...@outlook.com.au> wrote:

> Hi Greg,
>
> We are using it for our APIs and [FromBody] parameters are magically
> appearing. See for example http://api.professionaldevelopmenttrainin
> g.com/docs/#!/PublicBooking/V4PublicBookingsPost
>
>
>
> I don’t have any suggestions at this stage for what to check but I will
> dig around.
>
>
>
> Cheers,
> Grant
>
>
>
>
>
> Grant Castner
> 0458 770 749
> http://twitter.com/grantcastner
> https://au.linkedin.com/in/grantcastner
>
>
>
> *From: *Greg Keogh <gfke...@gmail.com>
> *Sent: *Tuesday, 27 June 2017 4:57 PM
> *To: *ozDotNet <ozdotnet@ozdotnet.com>
> *Subject: *Swashbuckle documentation
>
>
>
> Is anyone in here documenting a WebApi by adding Swashbuckle to the
> project? I've done so and it's working reasonably well with relatively
> little code or suffering. Although it's struggle at first to read
> conflicting articles and then figure out which xmldocs and attributes
> actually do anything and what code is needed in the SwaggerConfig file.
>
>
>
> My remaining problem is that controller [FromBody] parameters never appear
> in the generated documentation. I've spent hours futzing around and
> searched the whole Internet without any progress at all. Many samples hint
> that such parameters will magically appear in the output, but mine never
> do. Has anyone delved into this sort of thing?
>
>
>
> *Greg K*
>
>
>

Re: Swashbuckle documentation

[Greg Keogh]

>
> Totally a stab in a dark here but perhaps your MockStuff class has to be
> decorated with something before the "magic" code behind the scenes picks it
> up.


I did put a [DataContract] on it as an experiment that failed, but I'm
holding the same suspicion as you and I can't rule it out yet -- *GK*

Re: Swashbuckle documentation

[Bec C]

Totally a stab in a dark here but perhaps your MockStuff class has to be
decorated with something before the "magic" code behind the scenes picks it
up.

On Tuesday, 27 June 2017, Greg Keogh  wrote:

> We are using it for our APIs and [FromBody] parameters are magically
>> appearing.
>>
>
> Yes, just like many articles suggest. Great example.
>
> You can see a sample of my problem here:
> https://www.orthogonal.net.au/pegwebapi/swagger/ui/index#!/
> Session/Session_MockMethod
>
> I've pasted below a picture of the controller source code method with a
> body parameter that doesn't appear in the output. What's different about
> your method? Are there any special annotations on the class in the body?
>
> Note that I had to write an IOperationFilter class to get the headers to
> appear in the output Parameters list, which was an obscure and tricky thing
> to uncover.
>
> Also note that I'm not using YAML to define the API, I'm documenting an
> existing API which they call the bottom-up approach.
>
> *GK*
>
> [image: Inline images 2]
>

Re: Swashbuckle documentation

[Greg Keogh]

>
> We are using it for our APIs and [FromBody] parameters are magically
> appearing.
>

Yes, just like many articles suggest. Great example.

You can see a sample of my problem here:
https://www.orthogonal.net.au/pegwebapi/swagger/ui/index#!/Session/Session_MockMethod

I've pasted below a picture of the controller source code method with a
body parameter that doesn't appear in the output. What's different about
your method? Are there any special annotations on the class in the body?

Note that I had to write an IOperationFilter class to get the headers to
appear in the output Parameters list, which was an obscure and tricky thing
to uncover.

Also note that I'm not using YAML to define the API, I'm documenting an
existing API which they call the bottom-up approach.

*GK*

[image: Inline images 2]

RE: Swashbuckle documentation

[Grant Castner]

Hi Greg,
We are using it for our APIs and [FromBody] parameters are magically appearing. 
See for example 
http://api.professionaldevelopmenttraining.com/docs/#!/PublicBooking/V4PublicBookingsPost

I don’t have any suggestions at this stage for what to check but I will dig 
around.

Cheers,
Grant


Grant Castner
0458 770 749
http://twitter.com/grantcastner
https://au.linkedin.com/in/grantcastner

From: Greg Keogh<mailto:gfke...@gmail.com>
Sent: Tuesday, 27 June 2017 4:57 PM
To: ozDotNet<mailto:ozdotnet@ozdotnet.com>
Subject: Swashbuckle documentation

Is anyone in here documenting a WebApi by adding Swashbuckle to the project? 
I've done so and it's working reasonably well with relatively little code or 
suffering. Although it's struggle at first to read conflicting articles and 
then figure out which xmldocs and attributes actually do anything and what code 
is needed in the SwaggerConfig file.

My remaining problem is that controller [FromBody] parameters never appear in 
the generated documentation. I've spent hours futzing around and searched the 
whole Internet without any progress at all. Many samples hint that such 
parameters will magically appear in the output, but mine never do. Has anyone 
delved into this sort of thing?

Greg K

Swashbuckle documentation

[Greg Keogh]

Is anyone in here documenting a WebApi by adding Swashbuckle to the
project? I've done so and it's working reasonably well with relatively
little code or suffering. Although it's struggle at first to read
conflicting articles and then figure out which xmldocs and attributes
actually do anything and what code is needed in the SwaggerConfig file.

My remaining problem is that controller [FromBody] parameters never appear
in the generated documentation. I've spent hours futzing around and
searched the whole Internet without any progress at all. Many samples hint
that such parameters will magically appear in the output, but mine never
do. Has anyone delved into this sort of thing?

*Greg K*