Provide explicit support for RESTier about swashbuckle.odata HOT 16 CLOSED

Steps to Repro:
Here are the instructions: http://odata.github.io/RESTier/#11-40-Bootstrap

Basically all you do is:
Install-Package Microsoft.RESTier -Pre
Add an EF DBContext and model

Then register RESTierRoute in WebAPIConfig.cs

using System.Web.Http;
using NorthwindAPI.Models;
using Microsoft.Restier.EntityFramework;
using Microsoft.Restier.WebApi;
using Microsoft.Restier.WebApi.Batch;

namespace NorthwindAPI
{
public static class WebApiConfig
{
public async static void Register(HttpConfiguration config)
{
await config.MapRestierRoute>(
"Northwind",
"Northwind/v4",
new RestierBatchHandler(GlobalConfiguration.DefaultServer));
}
}
}

Now addSWashbuckle and SwashbuckOData and try swagger.

Thanks in advance.

from swashbuckle.odata.

Any past support for RESTier was un-intended/lucky. :-) This issue will provide explicit support along with unit tests to verify.

from swashbuckle.odata.

Per @joshbooker: "I think one difference over vanilla WebAPI OData is that, with RESTier, there are zero controllers in user code. RESTier exposes OData directly from models in EF DBContext eliminating need for a controller per entity type."

Thanks for the info.

from swashbuckle.odata.

@rbeauchamp To test with RESTier you can simply add RESTier nuget and then alter WebAPIConfig.cs like so:
joshbooker@dbfcecc

from swashbuckle.odata.

Thanks. Do you know if vanilla webapi-odata works well with RESTier in the same project? I notice that you commented out the webapi-odata configs from WebApiConfig. I want to maintain tests against both WebApi-OData and RESTier.

from swashbuckle.odata.

Yes, It will work as long as routeName and routePrefix are different for MapRestierRoute and MapODataServeRoute.

from swashbuckle.odata.

@joshbooker RESTier support is now available on NuGet.

So I've learned a lot about RESTier: it provides a single, generic controller named 'Restier' that all EF DBContexts leverage. So in Swashbuckle/Swagger, because the paths are grouped by controller (under the assumption of one Entity per controller), all RESTier Entities are currently under the same grouping of 'Restier'. It will take some additional work to group by EntityType/Resource, to simulate a 'controller per Entity/Resource'.

from swashbuckle.odata.

@joshbooker Hey Josh, FYI as of v2.5.1 RESTier endpoints are grouped by EntitySet name rather than 'Restier'.

from swashbuckle.odata.

@rbeauchamp
Thanks for all your hard work! I tried with Northwind db and got this:
#18

from swashbuckle.odata.

Hi again @rbeauchamp, Happy New Year to you! Looks like this repo is taking off. Thanks again for your hard work.

Not sure if this is related to the grouping you mention above, but in 2.5.2, I'm still seeing 'Restier_' in my operationIds. For example, instead of 'Restier_Get' I would expect 'Categories_Get'

      "paths": {
        "/Northwind/v4/Categories": {
          "get": {
            "tags": [ "Categories" ],
            "summary": "Returns the EntitySet Categories",
            "operationId": "Restier_Get",
        ...},
          "post": {
            "tags": [ "Categories" ],
            "summary": "Post a new entity to EntitySet Categories",
            "operationId": "Restier_Post",
            "consumes": [ ],
            "produces": [ ],
        ...},
        "/Northwind/v4/Categories({CategoryID})": {
          "get": {
            "tags": [ "Categories" ],
            "summary": "Returns the entity with the key from Categories",
            "operationId": "Restier_Get",
            "consumes": [ ],
            "produces": [ ],
        ...},

from swashbuckle.odata.

Hey @joshbooker. Happy New Year to you. Thanks! Yes, that is a bug, operationIds should be unique. Re-opening...

from swashbuckle.odata.

Thanks. At least if it would be EntityName_Get that would suffice. The uniqueness can be handled by a OperationFilter like so:

        internal class IncludeParameterNamesInOperationIdFilter : IOperationFilter
        {
            public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
            {
                if (operation.parameters != null)
                {
                    // Select the capitalized parameter names
                    var parameters = operation.parameters.Select(
                        p => CultureInfo.InvariantCulture.TextInfo.ToTitleCase(p.name)))
                        .Where(p => p.StartsWith("$") == false);

                    // Set the operation id to match the format "OperationByParam1AndParam2"
                    operation.operationId = string.Format(
                        "{0}By{1}",
                        operation.operationId,
                        string.Join("And", parameters));
                }
            }
        }

from swashbuckle.odata.

Hey @joshbooker, thank you for the operation filter. I included your code in the latest release because, technically, all operationIds should be unique in a swagger document, Restier or otherwise. So you shouldn't need your OperationFilter anymore, if you were using it.

The fix is available in v2.9.1. Please try it out and let me know if you have any issues. Thanks!

from swashbuckle.odata.

Thanks for the quick response.

Now I get an extra iteration of parameter names in operationId. For example, Categories_GetByCategoryidByCategoryid instead of Categories_GetByCategoryid.

Also, you might consider using only parameters p.@in == "path" . For example, Categories_PutByCategoryid instead of Categories_PutByCategoryidAndCategory

  "paths": {
    "/Northwind/v4/Categories": {
      "get": {
        "tags": [ "Categories" ],
        "summary": "Returns the EntitySet Categories",
        "operationId": "Categories_Get",
        "consumes": [ ],
        "produces": [ ],
        "parameters": [
          {
            "name": "$expand",
            ...},
          ...]},
      "post": {
        "tags": [ "Categories" ],
        "summary": "Post a new entity to EntitySet Categories",
        "operationId": "Categories_PostByCategoryByCategory",
        "consumes": [ ],
        "produces": [ ],
        "parameters": [
          {
            "name": "Category",
            "in": "body",
            "description": "The entity to post",
            "required": true,
            "schema": { "$ref": "#/definitions/Category" }
          }
        ],
        ...}
    },
    "/Northwind/v4/Categories({CategoryID})": {
      "get": {
        "tags": [ "Categories" ],
        "summary": "Returns the entity with the key from Categories",
        "operationId": "Categories_GetByCategoryidByCategoryid",
        "consumes": [ ],
        "produces": [ ],
        "parameters": [
          {
            "name": "CategoryID",
            "in": "path",
            "description": "key: CategoryID",
            "required": true,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "$select",....
     "put": {
        "tags": [ "Categories" ],
        "summary": "Replace entity in EntitySet Categories",
        "operationId": "Categories_PutByCategoryidAndCategoryByCategoryidAndCategory",
        "consumes": [ ],
        "produces": [ ],
        "parameters": [
          {
            "name": "CategoryID",
            "in": "path",
            "description": "key: CategoryID",
            "required": true,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "Category",
            "in": "body",
            "description": "The entity to put",
            "required": true,
            "schema": { "$ref": "#/definitions/Category" }
          }
        ],

from swashbuckle.odata.

Yes, thanks, good feedback. Try v2.9.2 and let me know.

from swashbuckle.odata.

@rbeauchamp Happy New Year!

Ironically almost exactly one year later, I'm back. Trying out some new swagger-based tooling and I found you are using a Document Filter to ensure unique OperationIDs. That's helpful in some cases, but what if we don't want them to be unique? The problem with having a document filter in your code, is we cannot override it in our SwaggerConfig.cs. I believe the doc filter happens after all the other filters in user code. I believe it would be better practice to ensure users have full capabilities of swashbuckle's configuration options. If they want unique then they can add an operation filter in user code. Thanks again.

from swashbuckle.odata.