Skip to content

Describes path operations descriptions from vocabulary annotations #104

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 4 commits into from
May 5, 2021
Merged

Describes path operations descriptions from vocabulary annotations #104

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2b31063
Add support for operation descriptions and update tests
irvinesunday Apr 26, 2021
206e9a4
Update tests for Entityset paths operations descriptions
irvinesunday Apr 26, 2021
02188d0
Code cleanup
irvinesunday Apr 27, 2021
b68cc7e
Update test OpenAPI output files.
irvinesunday Apr 27, 2021
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
2 changes: 2 additions & 0 deletions src/Microsoft.OpenApi.OData.Reader/Operation/EdmOperationImportOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ protected override void SetBasicInfo(OpenApiOperation operation)
{
operation.Summary = "Invoke " + (EdmOperationImport.IsActionImport() ? "actionImport " : "functionImport ") + EdmOperationImport.Name;

operation.Description = Context.Model.GetDescriptionAnnotation(EdmOperationImport);

if (Context.Settings.EnableOperationId)
{
if (EdmOperationImport.IsActionImport())
Expand Down
3 changes: 3 additions & 0 deletions src/Microsoft.OpenApi.OData.Reader/Operation/EdmOperationOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,9 @@ protected override void SetBasicInfo(OpenApiOperation operation)
// Summary
operation.Summary = "Invoke " + (EdmOperation.IsAction() ? "action " : "function ") + EdmOperation.Name;

// Description
operation.Description = Context.Model.GetDescriptionAnnotation(EdmOperation);

// OperationId
if (Context.Settings.EnableOperationId)
{
Expand Down
9 changes: 6 additions & 3 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 @@ -29,14 +29,17 @@ protected override void SetBasicInfo(OpenApiOperation operation)
// Summary
operation.Summary = "Delete entity from " + EntitySet.Name;

IEdmEntityType entityType = EntitySet.EntityType();

// Description
operation.Description = Context.Model.GetDescriptionAnnotation(entityType);

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

base.SetBasicInfo(operation);
}

/// <inheritdoc/>
Expand Down
9 changes: 6 additions & 3 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 @@ -30,14 +30,17 @@ protected override void SetBasicInfo(OpenApiOperation operation)
// Summary
operation.Summary = "Get entity from " + EntitySet.Name + " by key";

IEdmEntityType entityType = EntitySet.EntityType();

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a line to set the description in the base class.

I don't know why do you want to rewrite it using the entity type.

Maybe you need to change that logic:

  1. If we have description for the entity set, use it
  2. otherwise, if we have description for entity type, use it
  3. otherwise, leave it empty or use a default string.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we not expecting a scenario where we have descriptions for both entity set and entity? In such a scenario, we would end up setting entity set descriptions for entities, even though they have their own annotated descriptions.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean for "single entity request, the annotation should from entity type?".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typically, it should comes from entity set, not from entity type.
However, it seems we can't distinguish it from entity set or single entity.
So, I am ok for your changes.

// Description
operation.Description = Context.Model.GetDescriptionAnnotation(entityType);

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

base.SetBasicInfo(operation);
}

/// <inheritdoc/>
Expand Down
9 changes: 6 additions & 3 deletions src/Microsoft.OpenApi.OData.Reader/Operation/EntityPatchOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,17 @@ protected override void SetBasicInfo(OpenApiOperation operation)
// Summary
operation.Summary = "Update entity in " + EntitySet.Name;

IEdmEntityType entityType = EntitySet.EntityType();

// Description
operation.Description = Context.Model.GetDescriptionAnnotation(entityType);

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

base.SetBasicInfo(operation);
}

/// <inheritdoc/>
Expand Down
9 changes: 9 additions & 0 deletions src/Microsoft.OpenApi.OData.Reader/Operation/EntitySetOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,15 @@ protected override void Initialize(ODataContext context, ODataPath path)
EntitySet = navigationSourceSegment.NavigationSource as IEdmEntitySet;
}

/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Description
operation.Description = Context.Model.GetDescriptionAnnotation(EntitySet);

base.SetBasicInfo(operation);
}

/// <inheritdoc/>
protected override void SetTags(OpenApiOperation operation)
{
Expand Down
14 changes: 10 additions & 4 deletions src/Microsoft.OpenApi.OData.Reader/Operation/MediaEntityGetOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
// ------------------------------------------------------------

using Microsoft.OData.Edm;
using Microsoft.OData.Edm.Vocabularies;
using Microsoft.OpenApi.Models;
using Microsoft.OpenApi.OData.Common;
using Microsoft.OpenApi.OData.Edm;
Expand Down Expand Up @@ -31,8 +32,15 @@ protected override void SetBasicInfo(OpenApiOperation operation)
}
else
{
string typeName = EntitySet.EntityType().Name;
operation.Summary = $"Get media content for {typeName} from {EntitySet.Name}";
IEdmEntityType entityType = EntitySet.EntityType();
operation.Summary = $"Get media content for {entityType.Name} from {EntitySet.Name}";
}

// Description
IEdmVocabularyAnnotatable annotatableElement = GetAnnotatableElement();
if (annotatableElement != null)
{
operation.Description = Context.Model.GetDescriptionAnnotation(annotatableElement);
}

// OperationId
Expand All @@ -41,8 +49,6 @@ protected override void SetBasicInfo(OpenApiOperation operation)
string identifier = Path.LastSegment.Kind == ODataSegmentKind.StreamContent ? "Content" : Path.LastSegment.Identifier;
operation.OperationId = GetOperationId("Get", identifier);
}

base.SetBasicInfo(operation);
}

/// <inheritdoc/>
Expand Down
55 changes: 34 additions & 21 deletions src/Microsoft.OpenApi.OData.Reader/Operation/MediaEntityOperationalHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,28 +151,8 @@ protected IDictionary<string, OpenApiMediaType> GetContentDescription()
Format = "binary"
};

IEdmVocabularyAnnotatable annotatableElement = null;
IEdmEntityType entityType = EntitySet != null ? EntitySet.EntityType() : Singleton.EntityType();
ODataSegment lastSegmentStreamProp = Path.Segments.LastOrDefault(c => c is ODataStreamPropertySegment);

if (lastSegmentStreamProp != null)
{
// Get the annotatable stream property
// The stream property can either be a structural type or navigation type property
IEdmProperty property = GetStructuralProperty(entityType, lastSegmentStreamProp.Identifier);
if (property == null)
{
property = GetNavigationProperty(entityType, lastSegmentStreamProp.Identifier);
}

annotatableElement = property;
}
else
{
annotatableElement = entityType;
}

// Fetch the respective AcceptableMediaTypes
IEdmVocabularyAnnotatable annotatableElement = GetAnnotatableElement();
IEnumerable<string> mediaTypes = null;
if (annotatableElement != null)
{
Expand All @@ -199,6 +179,39 @@ protected IDictionary<string, OpenApiMediaType> GetContentDescription()
return content;
}

/// <summary>
/// Determines the annotatable element from the segments of a path.
/// </summary>
/// <returns>The annotable element.</returns>
protected IEdmVocabularyAnnotatable GetAnnotatableElement()
{
IEdmEntityType entityType = EntitySet != null ? EntitySet.EntityType() : Singleton.EntityType();
ODataSegment lastSegmentProp = Path.Segments.LastOrDefault(c => c is ODataStreamPropertySegment);

if (lastSegmentProp == null)
{
int pathCount = Path.Segments.Count;

// Retrieve the segment before the stream content segment
lastSegmentProp = Path.Segments.ElementAtOrDefault(pathCount - 2);

if (lastSegmentProp == null)
{
return null;
}
}

// Get the annotatable stream property
// The stream property can either be a structural type or navigation type property
IEdmProperty property = GetStructuralProperty(entityType, lastSegmentProp.Identifier);
if (property == null)
{
property = GetNavigationProperty(entityType, lastSegmentProp.Identifier);
}

return property;
}

private IEdmStructuralProperty GetStructuralProperty(IEdmEntityType entityType, string identifier)
{
return entityType.DeclaredStructuralProperties().FirstOrDefault(x => x.Name.Equals(identifier));
Expand Down
10 changes: 8 additions & 2 deletions src/Microsoft.OpenApi.OData.Reader/Operation/MediaEntityPutOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@

using System.Linq;
using Microsoft.OData.Edm;
using Microsoft.OData.Edm.Vocabularies;
using Microsoft.OpenApi.Models;
using Microsoft.OpenApi.OData.Common;
using Microsoft.OpenApi.OData.Edm;
Expand Down Expand Up @@ -35,14 +36,19 @@ protected override void SetBasicInfo(OpenApiOperation operation)
operation.Summary = $"Update media content for {typeName} in {EntitySet.Name}";
}

// Description
IEdmVocabularyAnnotatable annotatableElement = GetAnnotatableElement();
if (annotatableElement != null)
{
operation.Description = Context.Model.GetDescriptionAnnotation(annotatableElement);
}

// OperationId
if (Context.Settings.EnableOperationId)
{
string identifier = Path.LastSegment.Kind == ODataSegmentKind.StreamContent ? "Content" : Path.LastSegment.Identifier;
operation.OperationId = GetOperationId("Update", identifier);
}

base.SetBasicInfo(operation);
}

/// <inheritdoc/>
Expand Down
9 changes: 9 additions & 0 deletions src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,15 @@ protected override void Initialize(ODataContext context, ODataPath path)
}
}

/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Description
operation.Description = Context.Model.GetDescriptionAnnotation(NavigationProperty);

base.SetBasicInfo(operation);
}

/// <inheritdoc/>
protected override void SetTags(OpenApiOperation operation)
{
Expand Down
9 changes: 9 additions & 0 deletions src/Microsoft.OpenApi.OData.Reader/Operation/SingletonOperationHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,15 @@ protected override void Initialize(ODataContext context, ODataPath path)
Singleton = navigationSourceSegment.NavigationSource as IEdmSingleton;
}

/// <inheritdoc/>
protected override void SetBasicInfo(OpenApiOperation operation)
{
// Description
operation.Description = Context.Model.GetDescriptionAnnotation(Singleton);

base.SetBasicInfo(operation);
}

/// <inheritdoc/>
protected override void SetTags(OpenApiOperation operation)
{
Expand Down
1 change: 1 addition & 0 deletions test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EdmActionImportOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ public void CreateOperationForEdmActionImportReturnsCorrectOperation()
// Assert
Assert.NotNull(operation);
Assert.Equal("Invoke actionImport ResetDataSource", operation.Summary);
Assert.Equal("Resets the data source to default values.", operation.Description);
Assert.NotNull(operation.Tags);

Assert.NotNull(operation.Parameters);
Expand Down
1 change: 1 addition & 0 deletions test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EdmActionOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ public void CreateOperationForEdmActionReturnsCorrectOperation()
// Assert
Assert.NotNull(operation);
Assert.Equal("Invoke action ShareTrip", operation.Summary);
Assert.Equal("Details of the shared trip.", operation.Description);
Assert.NotNull(operation.Tags);
var tag = Assert.Single(operation.Tags);
Assert.Equal("People.Actions", tag.Name);
Expand Down
1 change: 1 addition & 0 deletions .../Microsoft.OpenAPI.OData.Reader.Tests/Operation/EdmFunctionImportOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ public void CreateOperationForEdmFunctionImportReturnsCorrectOperation()
// Assert
Assert.NotNull(operation);
Assert.Equal("Invoke functionImport GetPersonWithMostFriends", operation.Summary);
Assert.Equal("The person with most friends.", operation.Description);
Assert.NotNull(operation.Tags);
var tag = Assert.Single(operation.Tags);
Assert.Equal("People", tag.Name);
Expand Down
1 change: 1 addition & 0 deletions test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EdmFunctionOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ public void CreateOperationForEdmFunctionReturnsCorrectOperationHierarhicalClass
// Assert
Assert.NotNull(operation);
Assert.Equal($"Invoke function {functionName}", operation.Summary);
Assert.Equal("Collection of contract attachments.", operation.Description);
Assert.NotNull(operation.Tags);
var tag = Assert.Single(operation.Tags);
Assert.Equal($"{entitySetName}.Functions", tag.Name);
Expand Down
1 change: 1 addition & 0 deletions 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 @@ -37,6 +37,7 @@ public void CreateEntityDeleteOperationReturnsCorrectOperation(bool enableOperat
// Assert
Assert.NotNull(delete);
Assert.Equal("Delete entity from Customers", delete.Summary);
Assert.Equal("A business customer.", delete.Description);
Assert.NotNull(delete.Tags);
var tag = Assert.Single(delete.Tags);
Assert.Equal("Customers.Customer", tag.Name);
Expand Down
1 change: 1 addition & 0 deletions 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 @@ -38,6 +38,7 @@ public void CreateEntityGetOperationReturnsCorrectOperation(bool enableOperation
// Assert
Assert.NotNull(get);
Assert.Equal("Get entity from Customers by key", get.Summary);
Assert.Equal("A business customer.", get.Description);
Assert.NotNull(get.Tags);
var tag = Assert.Single(get.Tags);
Assert.Equal("Customers.Customer", tag.Name);
Expand Down
1 change: 1 addition & 0 deletions 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 @@ -37,6 +37,7 @@ public void CreateEntityPatchOperationReturnsCorrectOperation(bool enableOperati
// Assert
Assert.NotNull(patch);
Assert.Equal("Update entity in Customers", patch.Summary);
Assert.Equal("A business customer.", patch.Description);
Assert.NotNull(patch.Tags);
var tag = Assert.Single(patch.Tags);
Assert.Equal("Customers.Customer", tag.Name);
Expand Down
5 changes: 4 additions & 1 deletion 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 @@ -332,13 +332,16 @@ public static IEdmModel GetEdmModel(string annotation)
<edmx:DataServices>
<Schema Namespace=""NS"" xmlns=""http://docs.oasis-open.org/odata/ns/edm"">
<EntityType Name=""Customer"">
<Annotation Term=""Org.OData.Core.V1.Description"" String=""A business customer."" />
<Key>
<PropertyRef Name=""ID"" />
</Key>
<Property Name=""ID"" Type=""Edm.Int32"" Nullable=""false"" />
</EntityType>
<EntityContainer Name =""Default"">
<EntitySet Name=""Customers"" EntityType=""NS.Customer"" />
<EntitySet Name=""Customers"" EntityType=""NS.Customer"">
<Annotation Term=""Org.OData.Core.V1.Description"" String=""Collection of business customers."" />
</EntitySet>
</EntityContainer>
<Annotations Target=""NS.Default/Customers"">
{0}
Expand Down
5 changes: 4 additions & 1 deletion test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/EntitySetPostOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ private void VerifyEntitySetPostOperation(string annotation, bool enableOperatio
// Assert
Assert.NotNull(post);
Assert.Equal("Add new entity to " + entitySet.Name, post.Summary);
Assert.Equal("Collection of business customers.", post.Description);
Assert.NotNull(post.Tags);
var tag = Assert.Single(post.Tags);
Assert.Equal("Customers.Customer", tag.Name);
Expand Down Expand Up @@ -240,7 +241,9 @@ private static IEdmModel GetEdmModel(string annotation, bool hasStream = false)
<Property Name=""ID"" Type=""Edm.Int32"" Nullable=""false"" />
</EntityType>
<EntityContainer Name =""Default"">
<EntitySet Name=""Customers"" EntityType=""NS.Customer"" />
<EntitySet Name=""Customers"" EntityType=""NS.Customer"">
<Annotation Term=""Org.OData.Core.V1.Description"" String=""Collection of business customers."" />
</EntitySet>
</EntityContainer>
<Annotations Target=""NS.Customer"">
{1}
Expand Down
9 changes: 7 additions & 2 deletions test/Microsoft.OpenAPI.OData.Reader.Tests/Operation/MediaEntityGetOperationHandlerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ public void CreateMediaEntityGetOperationReturnsCorrectOperation(bool enableOper
<String>image/png</String>
<String>image/jpeg</String>
</Collection>
</Annotation>";
</Annotation>
<Annotation Term=""Org.OData.Core.V1.Description"" String=""The logo image."" />";

// Assert
VerifyMediaEntityGetOperation("", enableOperationId);
Expand Down Expand Up @@ -74,6 +75,7 @@ private void VerifyMediaEntityGetOperation(string annotation, bool enableOperati
Assert.NotNull(getOperation2);
Assert.Equal("Get media content for Todo from Todos", getOperation.Summary);
Assert.Equal("Get media content for the navigation property photo from me", getOperation2.Summary);
Assert.Equal("The user's profile photo.", getOperation2.Description);
Assert.NotNull(getOperation.Tags);
Assert.NotNull(getOperation2.Tags);

Expand All @@ -94,6 +96,7 @@ private void VerifyMediaEntityGetOperation(string annotation, bool enableOperati
Assert.Equal(2, getOperation.Responses[Constants.StatusCode200].Content.Keys.Count);
Assert.True(getOperation.Responses[Constants.StatusCode200].Content.ContainsKey("image/png"));
Assert.True(getOperation.Responses[Constants.StatusCode200].Content.ContainsKey("image/jpeg"));
Assert.Equal("The logo image.", getOperation.Description);

Assert.Equal(1, getOperation2.Responses[Constants.StatusCode200].Content.Keys.Count);
Assert.True(getOperation2.Responses[Constants.StatusCode200].Content.ContainsKey(Constants.ApplicationOctetStreamMediaType));
Expand Down Expand Up @@ -132,7 +135,9 @@ public static IEdmModel GetEdmModel(string annotation)
<Property Name = ""Description"" Type = ""Edm.String"" />
</EntityType>
<EntityType Name=""user"" OpenType=""true"">
<NavigationProperty Name = ""photo"" Type = ""microsoft.graph.profilePhoto"" ContainsTarget = ""true"" />
<NavigationProperty Name = ""photo"" Type = ""microsoft.graph.profilePhoto"" ContainsTarget = ""true"" >
<Annotation Term=""Org.OData.Core.V1.Description"" String=""The user's profile photo."" />
</NavigationProperty>
</EntityType>
<EntityType Name=""profilePhoto"" HasStream=""true"">
<Property Name = ""height"" Type = ""Edm.Int32"" />
Expand Down
Loading