Support new UseInlineDefinitionsForObjects flag

[sol-wasserman]

Problem

When a request/response has a nested object, there are two pieces of information missing from the generated doc file:

1. The property's summary is not displayed.
2. The Nullable marker is not shown for nullable properties.

---

Here's a screenshot of what it looks like now:

Here's a screenshot of the source code for the above:

As you can see, this property has a nice summary, and is nullable.

Here's a screenshot of what it I would expect:

Underlying Cause

It looks to me like the reason it's not generating that properly is because the object is only a reference, and Swagger doesn't support these on references. As the Swagger specification says, regarding $refs:

This object cannot be extended with additional properties and any properties added SHALL be ignored.

Proposed Solution

We have previously introduced an option to UseInlineDefinitionsForEnums. Among other things, this will show the summary of a property that is an enum, and will also show the Nullable marker accordingly.

This PR adds a similar UseInlineDefinitionsForObjects option. When enabled, it'll inline the whole schema, and will properly show the summary and whether it's nullable:

Copied from #2384 which was accidentally closed.

[ColKrumpler]

@domaindrivendev could this be evaluated to be merged in?

[jamesmcroft]

From the original PR for this change #2426, you'll want to add support for self-referencing types:

returnAsReference = !_generatorOptions.UseInlineDefinitionsForObjects ||
                                        dataContract.ObjectProperties.Any(prop =>
                                            prop.MemberType.IsAssignableFrom(dataContract.UnderlyingType) ||
                                            prop.MemberType.GenericTypeArguments.Any(type =>
                                                type.IsAssignableFrom(dataContract.UnderlyingType)));

[jamesmcroft]

The test for this to also validate the change:

        [Fact]
        public void GenerateSchema_SupportsOption_UseReferenceForSelfReferenceTypesWhenUseInlineDefinitionsForObjects()
        {
            var subject = Subject(
                configureGenerator: c => c.UseInlineDefinitionsForObjects = true
            );

            var schema = subject.GenerateSchema(typeof(SelfReferencingType), new SchemaRepository());

            Assert.NotNull(schema.Reference);
            Assert.Equal("SelfReferencingType", schema.Reference.Id);
        }

[martincostello]

Thanks for contributing - if you'd like to continue with this pull request, please rebase against the default branch to pick up our new CI.

[martincostello]

This seems reasonable to me - I think I've even researched this exact lack of summary (and maybe the nullability) myself before in the past.

If have no specific feedback other than than it looks like there's some comments from jamesmcroft that should be looked at.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 60.00000% with 2 lines in your changes are missing coverage. Please review.

Project coverage is 91.64%. Comparing base (45a2cb7) to head (3f8b012).

Files	Patch %	Lines
...DependencyInjection/SwaggerGenOptionsExtensions.cs	0.00%	2 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2533      +/-   ##
==========================================
- Coverage   91.70%   91.64%   -0.06%     
==========================================
  Files          91       91              
  Lines        3025     3029       +4     
  Branches      519      519              
==========================================
+ Hits         2774     2776       +2     
- Misses        251      253       +2     

Flag	Coverage Δ
Linux	91.64% <60.00%> (-0.06%)	⬇️
Windows	91.64% <60.00%> (-0.06%)	⬇️
macOS	91.64% <60.00%> (-0.06%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jamesmcroft]

This seems reasonable to me - I think I've even researched this exact lack of summary (and maybe the nullability) myself before in the past.

If have no specific feedback other than than it looks like there's some comments from jamesmcroft that should be looked at.

As the author of the original change being presented here, I know what has been included from my PR here will not work correctly for self-referencing types. Please consider bringing these additional changes from the original PR @sol-wasserman

[martincostello]

Can you add a test that exhibits the above is handled correctly, whether or not the non-test code is changed? If it then isn't, we should fix that somehow.

[sol-wasserman]

@jamesmcroft I got a little stuck trying to solve this. Your linked piece of code correctly solves for self-references, but I couldn't figure out how to solve for circular references that may be buried deeper into the tree.

Do you have any ideas?

[cervengoc]

Thank you for this PR, this is exactly what I was investigating. However, I'd like to suggest a little generalization.

I would like to have this option as a callback receiving at least the contract type which is about to be generated. So that way one can configure this in a much more flexible way, for example using this mode only for several types.