wwwlicious/servicestack-introspec

An introspection and specification plugin for ServiceStack

servicestack-introspec's Issues

Error if Service call returns collection of Result DTOs

A null reference exception is being thrown if a Service call returns a generic collection (e.g. IEnumerable).

E.g.

// This is fine
public ReturnDto Any(RequestDto){}

// As is this
public ReturnDto[] Any(RequestDto){}

// This is not
public IEnumerable<ReturnDto> Any(RequestDto){}

The issue is the call to Type.GetElementType() is returning null when the resourceType is an IEnumerable collection (PropertyEnricherManager ln46).

Type.GetElementType() is for Array types, need to update to use Type.GetGenericArguments if IEnumerable. See http://stackoverflow.com/questions/7072088/why-does-type-getelementtype-return-null

Return route config settings from introspec

there are settings in the apphost configuration which affect how requests are handled such as

http://docs.servicestack.net/routing#content-negotiation
config.AllowRouteContentTypeExtensions (.[xml|jsv|csv|json]on urls)

Also the auto route generation strategies need to be considered
http://docs.servicestack.net/routing#auto-route-generation-strategies

And routes can be added dynamically
http://docs.servicestack.net/routing#dynamically-adding-route-attributes

And IUrlFilter
http://docs.servicestack.net/routing#customize-urls-used-with-iurlfilter

Correct type typo

Rename ApiPropertyDocumention to be spelled correctly.

Rename Contraints

Replace usage of CLR Types in introspec dto's

To get maximum compatibility with generated language contracts, avoid using native CLR types in introspec DTOs

ApiContact uses CLR type Uri
Replace with a string, or simple ApiUrl dependency free class if subproperties are required like scheme, IsSecure etc

ApiPropertyDocumention uses System.Type for property ClrType.
Again replace with a simple poco class containing the properties of Type required (Name, IsPrimative, AssemblyQualifiedName` etc)

Add plugin startup errors to spec

Add any plugin errors that occurred in the apphost registration to the introspec output.

[Background]
One of the service validity checks to make for ServiceCop is that a registered service has started correctly. One thing to check, is to get the startup errors returned as part of the Introspec contract.

Add version to spec

Add an IntroSpec document version so that we can track/handle parsing changes

Add HasValidator flag to each DTO

For each DTO, output a boolean flag that indicates whether a validator class exists for the DTO type.

IApiResourceType does not contain Title

The IApiResourceType does not contain Title

Data Type field on ApiPropertyDocumentation

I'd like the DataType field from ApiMemberAttribute to end up in the spec.

Would you be okay if I submit a pull request to add it? Do you have any preference on the property name?

Rename the plugin links

Suggest renaming the plugin links to group and be easier to associate with the plugin

OpenAPI

ServiceStack have introduced the OpenApi spec in this commit

Can we leverage the spec DTO to pipe through our enrichers and create a IntroSpec.OpenApi nuget library?

Remove WebHostUrl requirement

For incoming requests to return the specifications, the baseUrl can be obtaining from the incoming request and therefore negates the requirement to explicitly set it in the Apphost. This applies to all introspec plugins

RouteAttribute is not splitting verbs correctly

The following

[Route("/some/route", "GET, POST")]
[Route("/some/route/{arg}", "GET")]   

is providing a Verb entries ['Get, Post', 'Get'] which I think needs split into three

Add type scope name to Request and Response

when validating the spec's request and response types, it would be useful to be able to know the scope name of the type.

1. You can't create an instance of the type from the spec typename string alone, you would need the dto copy from the spec's origin also
2. Determining information about the type from the string is likely to be fragile.

For example, I can use the scope to reliably determine if a type is from the CLR or not using

instance.GetType().Module.ScopeName == "CommonLanguageRuntimeLibrary"

It might also be an idea to add some additional type information for Requests and Responses such as instance.GetType().IsClass (not a interface or value type), instance.GetType().IsAbstract, instance.GetType().Module.Name, instance.GetType().AssemblyQualifiedName

Support additional exclusions

Currently we support the IgnoreDataMemberAttribute

There is also the IgnoreAttribute and [ApiMember(ExcludeInSchema = true)]

Should we also support them for exclusions?

replace IList<string> on Permissions

When generating typescript definitions, the IList CLR type cannot be generated.

Replace the two properties Any and All to use string[] instead to maximise compatibility when generating different language contracts.

https://github.com/MacLeanElectrical/servicestack-introspec/blob/master/src/ServiceStack.IntroSpec/ServiceStack.IntroSpec/Models/Permissions.cs

Create flattened type map

Return all the types that are being utilised in all classes/props for maximum x-plat compatibility (i.e. primitives).

It would be helpful to include this as a type map that flattens out all types used in the request and response dtos. It should walk all request and response types and properties and where not inherited from a primitive should also be walked. Collection item types/generics should also be checked. Duplicates should be discarded.

Primitives should be returned normalised, so System.String should just be string. number should be returned for all variants int, Int64, double, uInt32, short etc. (see openApi spec for example), bool for booleans, drop arrays so just string for string[] etc but collections other than array should be returned as they are.

Recursive types would need to be handled/escaped also.

This would allow easier checks and warnings where non-primitive types that are not explicitly returned in the type spec than Clr types are being used which potentially reduce reuse or compatibility across different languages/platforms when generating dtos/contracts.

Update the demo project

Update the demo project to provide a more real-world set of services (ala swagger petstore).

This is to give the ux something to default to once hosted and therefore provide something to test IDE integration against.

It should still try and include all the various permutations available but should return some static data.

Support Required Attributes

Both ServiceStack.DataAnnotations and System.ComponentModel.DataAnnotations contain a RequiredAttribute

Should this be supported in addition to the [ApiMember(IsRequired = true)]?

swagger 2.0

I noticed you already implemented an extension to support RAML.
Are you planning to support swagger 2.0 as well?

SS 5.0.x compatibility

Do you have plans to release a version compatible with ServiceStack >= 5.0.0?

Update XmlEnricher to read any XML docs for referenced dlls

The default implementation of IXmlDocumentationReader parses the XML documentation for entry assembly only.

The XML is parsed and saved in a lookup upfront for speed of processing later.

Update this to read XML documents for any referenced dll, not just the entry assembly.

PUT and DELETE verbs are ignored

I noticed the verbs PUT and DELETE provided through the Route attribute are ignored within ApiDocumentation.
ApiDocumentation -> Resources ->Actions does not list those verbs unless the service that handle the DTO (decorated with the Route attribute) contains an explicit method Put and/or Delete: using the Any method the 2 verbs are ignored.

public class MyDtoService : Service
{
    //public object Get(MyDto request) => new MyDtoResponse();
    //public object Delete(MyDto request) => new MyDtoResponse();
    //public object Post(MyDto request) => new MyDtoResponse();
    //public object Put(MyDto request) => new MyDtoResponse();
    public object Any(MyDto request) => new MyDtoResponse();
}

[Route("/items/{Name}/", "PUT")]
//[Route("/items", "POST")]
public class MyDto : IReturn<MyDtoResponse>
{
    ....
}

Add IsCached boolean to resources

The goal is to detect which responses will be cached.
The simple implementation would be to detect any usage of the [CacheResponse] attribute on the endpoint.

Not sure if Request.ToOptimisedResult or customised caching can be reliably added or if there aspects of the CacheFeature plugin that can be added also. (perhaps by looking up a key convention on a cache dictionary)

SS 4.5.4 compatibility

Hey

Will you be upgrading this project to be compatible with SS 4.5.4? I can see there is a develop branch that is targeting 4.5.0.

DataMember attribute

When there are formats that require the use of [DataMember] for serialization it would be helpful to have these against the dto and props

one example is http://docs.servicestack.net/protobuf-format where [DataMember(Order=N)] must be specified.

Another is http://docs.servicestack.net/soap-support where [DataContract] and [DataMember]

Soap goes further than this, requiring that the ANY method is used so this may not be worth supporting at the moment. From the docs it says:

Using Any will allow the Service to be executed on each HTTP Verb which is required for SOAP since all SOAP Requests are made with a HTTP POST Request wrapped inside a SOAP message and sent to the fixed /soap11 or /soap12 endpoints. You also want to make sure that all DTO models have [DataContract] attribute (and [DataMember] attribute for all properties) otherwise the XSD-schema embedded within the WSDL will be partially incomplete.

For fallback titles on requests and props, split typename by camelcase

Default the titles to split by camelcase so MyRequest becomes My Request

Suggested new Api* Attributes

Might be worth suggesting a couple of new Api attributes to add to servicestack, if not, they can just be added to introspec.

Name	AllowMultiple	ApplyTo	Suggested Signature
Category	Yes	Assembly, Class, Method	[ApiCategory(string category)]
Example	Yes	Method	[ApiExample(string url, string body)]
Tag	Yes	Assembly, Class, Method	[ApiTag(params string[] tags)]

Add list of external calls to IGateway.Send to ApiDocumentation

Background:
By capturing the DTO calls to IGateway.Send that are not part of the local service operations list, we can provide a list of the external service dependencies.

This list will be used to validate and provide warnings during service validation/registration for missing instances of any of those dependencies via the service registry, It can also be used when deploying the dependent services by enforcing their service contract consistency when in use by other services in the service registry.

Implementation:

1. First establish a list of the usages of IGateway.Send method.
2. Eliminate calls where the parameter type is in the service operations list

Notes:

To find all the usages, we can use a reflection-based disassembler to find all the references to the method.

Going forward, an alternative approach would be using Roslyn to provide compile-time syntax rewriting of a class to hold the list of external DTOs, but at present the hooks to autowire this via ICompileModule are inelegant and part of future roslyn plans to further develop.

Support OpenApi http attributes for allowable content type on actions

Related to this commit

ServiceStack/ServiceStack@d39adc6

ReflectionEnricher Stackoverflow exception

The reflectionenricher fails to detect circular type references in properties which leads to a stackoverflow exception.

Found this issue when trying to use ValidationResult as a property in a DtoResponse. It contains a property of IRequest which itself contains an IResponse property which contains an IRequest property and thus creates an infinite loop.

Need to add a check when using the property enricher that it does not process a type already in the parent tree and if so instead create a symbolic link in the spec (something we don't really have afaik)

raml endpoint not working

I'm trying to running the DemoService sample, but I'm getting the following error
"Required dependency of type Servicestack.IntroSpec.Raml.Services.Raml08Service could not be resolved."
invoking the "http://127.0.0.1:8090/spec/raml/0.8" endpoint using the "RAML 0.8" link within the metadatapage.
Debbugging the code, the line "https://github.com/MacLeanElectrical/servicestack-introspec-raml/blob/master/src/Servicestack.IntroSpec.Raml/ServiceStack.IntroSpec.Raml/RamlFeature.cs#L29" has been executed, but the service has not been added in the container