Skip to content

Summaries and Descriptions Mapping #206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Apr 7, 2022
Merged

Summaries and Descriptions Mapping #206

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
bce9abd
Handle Summaries and Descriptions from *Restrictions annotations in c…
finsharp Apr 5, 2022
e8733c0
make differentiating changes to test data.
georgend Apr 5, 2022
3a31a69
Differentiate summary from description.
georgend Apr 5, 2022
545d29a
Remove summary handling.
georgend Apr 5, 2022
200a5d3
Update tests.
georgend Apr 5, 2022
cf7b9f3
Use explicity typing.
georgend Apr 5, 2022
0f40d7b
Singleton.
georgend Apr 5, 2022
bea9474
Update CRUD operations summaries and descriptions
irvinesunday Apr 5, 2022
076c3e9
Merge pull request #2 from irvinesunday/is/summaries
georgend Apr 5, 2022
f74f442
Corrections.
georgend Apr 5, 2022
4828a91
update test data.
georgend Apr 5, 2022
f458f45
Update some CRUD operations summaries and descriptions
irvinesunday Apr 6, 2022
960c3c3
Update tests
irvinesunday Apr 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions src/Microsoft.OpenApi.OData.Reader/Operation/ComplexPropertyGetOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,6 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary
operation.Summary = $"Get {ComplexPropertySegment.Property.Name} property value";

// OperationId
if (Context.Settings.EnableOperationId)
{
Expand All @@ -46,8 +43,10 @@ protected override void SetBasicInfo(OpenApiOperation operation)
operation.OperationId = ComplexPropertySegment.Property.Name + "." + typeName + listOrGet + Utils.UpperFirstChar(typeName);
}

// Description
operation.Description = ReadRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(ComplexPropertySegment.Property);
// Summary and Description
var placeHolder = $"Get {ComplexPropertySegment.Property.Name} property value";
operation.Summary = ReadRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(ComplexPropertySegment.Property) ?? placeHolder;
operation.Description = ReadRestrictions?.LongDescription ?? Context.Model.GetLongDescriptionAnnotation(ComplexPropertySegment.Property) ?? placeHolder;

base.SetBasicInfo(operation);
}
Expand Down
11 changes: 5 additions & 6 deletions src/Microsoft.OpenApi.OData.Reader/Operation/ComplexPropertyPostOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ internal class ComplexPropertyPostOperationHandler : ComplexPropertyBaseOperatio
protected override void Initialize(ODataContext context, ODataPath path)
{
base.Initialize(context, path);
if(!ComplexPropertySegment.Property.Type.IsCollection())
if (!ComplexPropertySegment.Property.Type.IsCollection())
{
throw new InvalidOperationException("OData conventions do not support POSTing to a complex property that is not a collection.");
}
Expand All @@ -39,18 +39,17 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary
operation.Summary = $"Sets a new value for the collection of {ComplexPropertySegment.ComplexType.Name}.";

// OperationId
if (Context.Settings.EnableOperationId)
{
string typeName = ComplexPropertySegment.ComplexType.Name;
operation.OperationId = ComplexPropertySegment.Property.Name + "." + typeName + ".Set" + Utils.UpperFirstChar(typeName);
}

// Description
operation.Description = InsertRestrictions?.Description;
// Summary and Description
var placeHolder = $"Sets a new value for the collection of {ComplexPropertySegment.ComplexType.Name}.";
operation.Summary = InsertRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(ComplexPropertySegment.Property) ?? placeHolder;
operation.Description = InsertRestrictions?.LongDescription ?? Context.Model.GetLongDescriptionAnnotation(ComplexPropertySegment.Property) ?? placeHolder;

base.SetBasicInfo(operation);
}
Expand Down
9 changes: 4 additions & 5 deletions src/Microsoft.OpenApi.OData.Reader/Operation/ComplexPropertyUpdateOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,10 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary
operation.Summary = $"Update property {ComplexPropertySegment.Property.Name} value.";

// Description
operation.Description = UpdateRestrictions?.Description;
// Summary and Description
var placeHolder = $"Update property {ComplexPropertySegment.Property.Name} value.";
operation.Summary = UpdateRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(ComplexPropertySegment.Property) ?? placeHolder;
operation.Description = UpdateRestrictions?.LongDescription ?? Context.Model.GetLongDescriptionAnnotation(ComplexPropertySegment.Property) ?? placeHolder;

// OperationId
if (Context.Settings.EnableOperationId)
Expand Down
7 changes: 3 additions & 4 deletions src/Microsoft.OpenApi.OData.Reader/Operation/EntityDeleteOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,12 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary
operation.Summary = "Delete entity from " + EntitySet.Name;

IEdmEntityType entityType = EntitySet.EntityType();

// Description
operation.Description = DeleteRestrictions?.Description;
var placeHolder = "Delete entity from " + EntitySet.Name;
operation.Summary = DeleteRestrictions?.Description ?? placeHolder;
operation.Description = DeleteRestrictions?.LongDescription ?? placeHolder;

// OperationId
if (Context.Settings.EnableOperationId)
Expand Down
9 changes: 4 additions & 5 deletions src/Microsoft.OpenApi.OData.Reader/Operation/EntityGetOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,12 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary
operation.Summary = "Get entity from " + EntitySet.Name + " by key";

IEdmEntityType entityType = EntitySet.EntityType();

// Description
operation.Description = ReadRestrictions?.ReadByKeyRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(entityType);
var placeHolder = "Get entity from " + EntitySet.Name + " by key";
operation.Summary = ReadRestrictions?.ReadByKeyRestrictions?.Description ?? Context.Model.GetLongDescriptionAnnotation(entityType) ?? placeHolder;
operation.Description = ReadRestrictions?.ReadByKeyRestrictions?.LongDescription ?? Context.Model.GetLongDescriptionAnnotation(entityType) ?? placeHolder;

// OperationId
if (Context.Settings.EnableOperationId)
Expand Down Expand Up @@ -132,7 +131,7 @@ protected override void SetResponses(OpenApiOperation operation)
}

protected override void SetSecurity(OpenApiOperation operation)
{
{
if (ReadRestrictions == null)
{
return;
Expand Down
9 changes: 4 additions & 5 deletions src/Microsoft.OpenApi.OData.Reader/Operation/EntitySetGetOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,18 +40,17 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary
operation.Summary = "Get entities from " + EntitySet.Name;
// Summary and Descriptions
var placeHolder = "Get entities from " + EntitySet.Name;
operation.Summary = ReadRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(EntitySet) ?? placeHolder;
operation.Description = ReadRestrictions?.LongDescription ?? Context.Model.GetLongDescriptionAnnotation(EntitySet) ?? placeHolder;

// OperationId
if (Context.Settings.EnableOperationId)
{
string typeName = EntitySet.EntityType().Name;
operation.OperationId = EntitySet.Name + "." + typeName + ".List" + Utils.UpperFirstChar(typeName);
}

// Description
operation.Description = ReadRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(EntitySet);
}

protected override void SetExtensions(OpenApiOperation operation)
Expand Down
9 changes: 4 additions & 5 deletions src/Microsoft.OpenApi.OData.Reader/Operation/EntitySetPostOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,18 +39,17 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary
operation.Summary = "Add new entity to " + EntitySet.Name;
// Summary and Description
var placeHolder = "Add new entity to " + EntitySet.Name;
operation.Summary = InsertRestrictions?.Description ?? placeHolder;
operation.Description = InsertRestrictions?.LongDescription ?? placeHolder;

// OperationId
if (Context.Settings.EnableOperationId)
{
string typeName = EntitySet.EntityType().Name;
operation.OperationId = EntitySet.Name + "." + typeName + ".Create" + Utils.UpperFirstChar(typeName);
}

// Description
operation.Description = InsertRestrictions?.Description;
}

/// <inheritdoc/>
Expand Down
7 changes: 3 additions & 4 deletions src/Microsoft.OpenApi.OData.Reader/Operation/EntityUpdateOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,12 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary
operation.Summary = "Update entity in " + EntitySet.Name;

IEdmEntityType entityType = EntitySet.EntityType();

// Description
operation.Description = UpdateRestrictions?.Description;
var placeHolder = "Update entity in " + EntitySet.Name;
operation.Summary = UpdateRestrictions?.Description ?? placeHolder;
operation.Description = UpdateRestrictions?.LongDescription ?? placeHolder;

// OperationId
if (Context.Settings.EnableOperationId)
Expand Down
9 changes: 4 additions & 5 deletions src/Microsoft.OpenApi.OData.Reader/Operation/SingletonGetOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,18 +39,17 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary, this summary maybe update in the base function call.
operation.Summary = "Get " + Singleton.Name;
// Summary and Descriptions
var placeHolder = "Get " + Singleton.Name;
operation.Summary = ReadRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(Singleton) ?? placeHolder;
operation.Description = ReadRestrictions?.LongDescription ?? Context.Model.GetLongDescriptionAnnotation(Singleton) ?? placeHolder;

// OperationId, it should be unique among all operations described in the API.
if (Context.Settings.EnableOperationId)
{
string typeName = Singleton.EntityType().Name;
operation.OperationId = Singleton.Name + "." + typeName + ".Get" + Utils.UpperFirstChar(typeName);
}

// Description
operation.Description = ReadRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(Singleton);
}

/// <inheritdoc/>
Expand Down
11 changes: 5 additions & 6 deletions src/Microsoft.OpenApi.OData.Reader/Operation/SingletonPatchOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,18 +39,17 @@ protected override void Initialize(ODataContext context, ODataPath path)
/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Summary, this summary maybe update in the base function call.
operation.Summary = "Update " + Singleton.Name;
// Summary and Descriptions
var placeHolder = "Update " + Singleton.Name;
operation.Summary = UpdateRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(Singleton) ?? placeHolder;
operation.Description = UpdateRestrictions?.LongDescription ?? Context.Model.GetLongDescriptionAnnotation(Singleton) ?? placeHolder;

// OperationId
if (Context.Settings.EnableOperationId)
{
string typeName = Singleton.EntityType().Name;
operation.OperationId = Singleton.Name + "." + typeName + ".Update" + Utils.UpperFirstChar(typeName);
}

// Description
operation.Description = UpdateRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(Singleton);
}

/// <inheritdoc/>
Expand Down Expand Up @@ -97,7 +96,7 @@ protected override void SetRequestBody(OpenApiOperation operation)
/// <inheritdoc/>
protected override void SetResponses(OpenApiOperation operation)
{
operation.AddErrorResponses(Context.Settings, true);
operation.AddErrorResponses(Context.Settings, true);
base.SetResponses(operation);
}

Expand Down
4 changes: 2 additions & 2 deletions ...Microsoft.OpenAPI.OData.Reader.Tests/Operation/ComplexPropertyGetOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ public void CreateComplexPropertyGetOperationReturnsCorrectOperationForSingle(bo

// Assert
Assert.NotNull(get);
Assert.Equal("Get BillingAddress property value", get.Summary);
Assert.Equal("Get the BillingAddress.", get.Summary);
Assert.Equal("Get the BillingAddress.", get.Description);

Assert.NotNull(get.Parameters);
Expand Down Expand Up @@ -77,7 +77,7 @@ public void CreateComplexPropertyGetOperationReturnsCorrectOperationForCollectio

// Assert
Assert.NotNull(get);
Assert.Equal("Get AlternativeAddresses property value", get.Summary);
Assert.Equal("The AlternativeAddresses.", get.Summary);
Assert.Equal("The AlternativeAddresses.", get.Description);

Assert.NotNull(get.Parameters);
Expand Down
6 changes: 3 additions & 3 deletions ...crosoft.OpenAPI.OData.Reader.Tests/Operation/ComplexPropertyPatchOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ public void CreateComplexPropertyDeleteOperationReturnsCorrectOperationForSingle

// Assert
Assert.NotNull(patch);
Assert.Equal("Update property BillingAddress value.", patch.Summary);
Assert.Equal("Update the BillingAddress.", patch.Summary);
Assert.Equal("Update the BillingAddress.", patch.Description);

Assert.NotNull(patch.Parameters);
Expand Down Expand Up @@ -77,8 +77,8 @@ public void CreateComplexPropertyPostOperationReturnsCorrectOperationForCollecti

// Assert
Assert.NotNull(patch);
Assert.Equal("Update property AlternativeAddresses value.", patch.Summary);
Assert.Null(patch.Description);
Assert.Equal("The AlternativeAddresses.", patch.Summary);
Assert.Equal("The AlternativeAddresses.", patch.Description);

Assert.NotNull(patch.Parameters);
Assert.Equal(1, patch.Parameters.Count); //id
Expand Down
2 changes: 1 addition & 1 deletion ...icrosoft.OpenAPI.OData.Reader.Tests/Operation/ComplexPropertyPostOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ public void CreateComplexPropertyPostOperationReturnsCorrectOperationForCollecti

// Assert
Assert.NotNull(post);
Assert.Equal("Sets a new value for the collection of Address.", post.Summary);
Assert.Equal("Create AlternativeAddress.", post.Summary);
Assert.Equal("Create a new AlternativeAddress.", post.Description);

Assert.NotNull(post.Parameters);
Expand Down
6 changes: 4 additions & 2 deletions ...Microsoft.OpenAPI.OData.Reader.Tests/Operation/ComplexPropertyPutOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,8 @@ public void CreateComplexPropertyDeleteOperationReturnsCorrectOperationForSingle

// Assert
Assert.NotNull(put);
Assert.Equal("Update property BillingAddress value.", put.Summary);
Assert.Equal("Update the BillingAddress.", put.Summary);
Assert.Equal("Update the BillingAddress.", put.Description);

Assert.NotNull(put.Parameters);
Assert.Equal(1, put.Parameters.Count); //id
Expand Down Expand Up @@ -76,7 +77,8 @@ public void CreateComplexPropertyPostOperationReturnsCorrectOperationForCollecti

// Assert
Assert.NotNull(put);
Assert.Equal("Update property AlternativeAddresses value.", put.Summary);
Assert.Equal("The AlternativeAddresses.", put.Summary);
Assert.Equal("The AlternativeAddresses.", put.Description);

Assert.NotNull(put.Parameters);
Assert.Equal(1, put.Parameters.Count); //id
Expand Down
2 changes: 1 addition & 1 deletion test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EntityDeleteOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ public void CreateEntityDeleteOperationReturnsCorrectOperation(bool enableOperat

// Assert
Assert.NotNull(delete);
Assert.Equal("Delete entity from Customers", delete.Summary);
Assert.Equal("Delete a customer.", delete.Summary);
Assert.Equal("Delete a customer.", delete.Description);
Assert.NotNull(delete.Tags);
var tag = Assert.Single(delete.Tags);
Expand Down
2 changes: 1 addition & 1 deletion test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EntityGetOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ public void CreateEntityGetOperationReturnsCorrectOperation(bool enableOperation

// Assert
Assert.NotNull(get);
Assert.Equal("Get entity from Customers by key", get.Summary);
Assert.Equal("Get a customer.", get.Summary);
Assert.Equal("Get a customer.", get.Description);
Assert.NotNull(get.Tags);
var tag = Assert.Single(get.Tags);
Expand Down
2 changes: 1 addition & 1 deletion test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EntityPatchOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ public void CreateEntityPatchOperationReturnsCorrectOperation(bool enableOperati

// Assert
Assert.NotNull(patch);
Assert.Equal("Update entity in Customers", patch.Summary);
Assert.Equal("Update a customer.", patch.Summary);
Assert.Equal("Update a customer.", patch.Description);
Assert.NotNull(patch.Tags);
var tag = Assert.Single(patch.Tags);
Expand Down
2 changes: 1 addition & 1 deletion test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EntityPutOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ public void CreateEntityPutOperationReturnsCorrectOperation(bool enableOperation

// Assert
Assert.NotNull(putOperation);
Assert.Equal("Update entity in Customers", putOperation.Summary);
Assert.Equal("Update a customer.", putOperation.Summary);
Assert.Equal("Update a customer.", putOperation.Description);
Assert.NotNull(putOperation.Tags);
var tag = Assert.Single(putOperation.Tags);
Expand Down
11 changes: 9 additions & 2 deletions test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EntitySetGetOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ public void CreateEntitySetGetOperationReturnsCorrectOperation(bool enableOperat

// Assert
Assert.NotNull(get);
Assert.Equal("Get entities from " + entitySet.Name, get.Summary);
Assert.Equal("List customers.", get.Summary);
Assert.Equal("List customers.", get.Description);
Assert.NotNull(get.Tags);
var tag = Assert.Single(get.Tags);
Expand Down Expand Up @@ -340,17 +340,20 @@ public static IEdmModel GetEdmModel(string annotation)
<Annotation Term=""Org.OData.Capabilities.V1.ReadRestrictions"">
<Record>
<PropertyValue Property=""Description"" String=""Get the BillingAddress."" />
<PropertyValue Property=""LongDescription"" String=""Get the BillingAddress."" />
</Record>
</Annotation>
<Annotation Term=""Org.OData.Capabilities.V1.UpdateRestrictions"">
<Record>
<PropertyValue Property=""Description"" String=""Update the BillingAddress."" />
<PropertyValue Property=""LongDescription"" String=""Update the BillingAddress."" />
</Record>
</Annotation>
</Property>
<Property Name=""MailingAddress"" Type=""NS.Address"" Nullable=""false"" />
<Property Name=""AlternativeAddresses"" Type=""Collection(NS.Address)"" Nullable=""false"">
<Annotation Term=""Org.OData.Core.V1.Description"" String=""The AlternativeAddresses."" />
<Annotation Term=""Org.OData.Core.V1.Description"" String=""The AlternativeAddresses."" />
<Annotation Term=""Org.OData.Core.V1.LongDescription"" String=""The AlternativeAddresses."" />
</Property>
</EntityType>
<EntityContainer Name =""Default"">
Expand All @@ -365,21 +368,25 @@ public static IEdmModel GetEdmModel(string annotation)
<Annotation Term=""Org.OData.Capabilities.V1.ReadRestrictions"">
<Record>
<PropertyValue Property=""Description"" String=""List customers."" />
<PropertyValue Property=""LongDescription"" String=""List customers."" />
<PropertyValue Property=""ReadByKeyRestrictions"">
<Record>
<PropertyValue Property=""Description"" String=""Get a customer."" />
<PropertyValue Property=""LongDescription"" String=""Get a customer."" />
</Record>
</PropertyValue>
</Record>
</Annotation>
<Annotation Term=""Org.OData.Capabilities.V1.UpdateRestrictions"">
<Record>
<PropertyValue Property=""Description"" String=""Update a customer."" />
<PropertyValue Property=""LongDescription"" String=""Update a customer."" />
</Record>
</Annotation>
<Annotation Term=""Org.OData.Capabilities.V1.DeleteRestrictions"">
<Record>
<PropertyValue Property=""Description"" String=""Delete a customer."" />
<PropertyValue Property=""LongDescription"" String=""Delete a customer."" />
</Record>
</Annotation>
</Annotations>
Expand Down
Loading