Server API stubs provider

[sergey-tihon]

https://github.com/panesofglass/SwaggerProvider/pull/1/files

[panesofglass]

Interested in thoughts here. Should this be a type provider based on OWIN or ASP.NET Core types? Or should this potentially be a code generator tool or something else entirely?

[panesofglass]

As I've been rebasing my prototype on top of the dev branch, I realized the right abstraction may be the System.Net.Http types for the following reasons:

1. This library already has an internal dependency on System.Net.Http for the HttpClient
2. HttpRequestMessage -> Task<HttpResponseMessage works on top of OWIN and Azure Functions and provides types that can easily be mapped into other hosts, e.g. Suave, Giraffe, etc.
3. While OWIN is still a great hosting option, it is not the most efficient nor something everyone will want to deal with, especially if they just want a simple API handler to host somewhere.

Thoughts? I'm going to continue rebasing with this idea in mind and hopefully make more progress towards actually generating the function signature that accepts the generated request type and returns the generated response type.

[sergey-tihon]

I agree with the implementation based on System.Net.Http types, and HttpRequestMessage -> Task<HttpResponseMessage> signature.

I think that we should do the following (in big)

type IContract = // provided interface with all infered signatures
   begin end // one method per operation from the schema

type ProvidedClient(host, params) =
   // virtual methods for serialization, deserialization, HTTP call interceptor and etc
   // virtual Call method `HttpRequestMessage -> Task<HttpResponseMessage>` 
   interface IContract with 
      // method for each operation, build HttpRequestMessage for each operation and call `Call` method

type DefaultServer() =
   // for those who want to implement only some part of the contract (for example for testing)
   interface IContract with 
      // default implementation for each method, throw NotImplementedException

type OwinHost(impl: IContract) =
   // Methods to plug into OWIN pipeline
   // Routing generated based on the schema, that identifies operation, extract data from HttpRequestMessage and call the appropriate method from `impl`

So when we want to implement server API based on the generated schema, we implement the IContract interface (or partially implement it using inheritance from DefaultServer) and then plug this implementation into OWIN pipeline using provided OwinHost.

Thoughts?

[panesofglass]

@sergey-tihon I like that! I think that's a bit simpler, too, than generating a type with methods accepting implementation callbacks. Is there already an interface generated for ProvidedClient, or will that be new?

OwinHost should also be a generated type that accepts the interface implementation? I think just Host is a better name, as we may want to make mappings for different kinds of hosts. Would that work?

Another question: you mention in your comment one operation per interface, right? What about grouping those by controller prefix? By default, it would generate separate contracts per operation, but if IgnoreControllerPrefix = false then generate by controller prefix. That would more closely model what people think of as controllers, which might be more familiar/comfortable for some.

Lastly, once I make some progress on this, would you like me to re-target my PR to this repository? Sounds like there is interest in pulling it in eventually.

[panesofglass]

Is it possible to generate an interface, or will this need to be some sort of base class? Can you generate an abstract type? I'm fairly new to type providers, so I'm not sure how to gen the IContract.

Found the answer: http://blog.mavnn.co.uk/modelling-inheritance-with-inheritance/

[sergey-tihon]

Is there already an interface generated for ProvidedClient, or will that be new?

No, but I think that it is the good thing to do.

OwinHost should also be a generated type that accepts the interface implementation?

Yes, plus maybe some other configuration parameters

I think just Host is a better name, as we may want to make mappings for different kinds of hosts. Would that work?

Yes, names in my sample are conceptual, so if you can do better names - I am fine with it (ServerHost, ApiHost or just Host)

Another question: you mention in your comment one operation per interface, right?

My bad, I meant one operation = one method.

What about grouping those by controller prefix? By default, it would generate separate contracts per operation, but if IgnoreControllerPrefix = false then generate by controller prefix.

Agree here as well. It is even implemented in dev branch, TP can provide one client by the controller.
But in this case, we probably want to have one host that accept all controller's interfaces. What do you think?

type OwinHost(impl1: IContract1, impl2: IContract2, ... implN: IContractN) =

when you do not want to provide impl, you use DefaultServerN

Lastly, once I make some progress on this, would you like me to re-target my PR to this repository?

Sure, just want to ask you to do this!

[panesofglass]

I was trying to find how to apply an interface implementation in a type provider and mostly found problems without solutions. Is it supported? Per @mavnn’s posts, it seems neither abstract classes nor interfaces can be successfully added to generated types, but perhaps that has changed. Any pointers?

[panesofglass]

As to your comments, I’m fully on board and excited to make it happen!

[panesofglass]

Last question: should we generate all this from one type provider? You could then create instances of client or host depending on use case, and you would get a shared set of interfaces, for whatever that is worth.

[sergey-tihon]

I was trying to find how to apply an interface implementation in a type provider and mostly found problems without solutions. Is it supported?

I hope so, but I am not sure... We need some experiments, maybe abstract class will work instead of interface (if we will have no luck with interface)

What I know:

• Swagger spec support polymorphist in type definition, so we may want to provide type that inherit one from other at some point - https://github.com/fsprojects/SwaggerProvider/blob/dev/src/SwaggerProvider.Runtime/Parser/Parsers.fs#L252
• We could override ctor and call base ctor and it works - https://github.com/fsprojects/SwaggerProvider/blob/dev/src/SwaggerProvider.DesignTime/OperationCompiler.fs#L282-L288
• We could override methods like .ToString, just need to set correct attributes SetMethodAttrs- https://github.com/fsprojects/SwaggerProvider/blob/dev/src/SwaggerProvider.DesignTime/DefinitionCompiler.fs#L225-L258

Last question: should we generate all this from one type provider? You could then create instances of client or host depending on use case, and you would get a shared set of interfaces, for whatever that is worth.

I think that one TP is OK, I do not really see reason to separate

[panesofglass]

Once I get interface generation working, I will submit a PR here. For now, I think fsprojects/FSharp.TypeProviders.SDK#211 is blocking progress. That, or my TP-fu is worse than useless, and I should sign up for an FSSF mentor to help me.