wwwlicious / servicestack-introspec Goto Github PK
View Code? Open in Web Editor NEWAn introspection and specification plugin for ServiceStack
License: Other
An introspection and specification plugin for ServiceStack
License: Other
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
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
Rename ApiPropertyDocumention
to be spelled correctly.
Rename Contraints
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 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 an IntroSpec document version so that we can track/handle parsing changes
For each DTO, output a boolean flag that indicates whether a validator class exists for the DTO type.
The IApiResourceType
does not contain Title
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?
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?
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
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
when validating the spec's request and response types, it would be useful to be able to know the scope name of the type.
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
Currently we support the IgnoreDataMemberAttribute
There is also the IgnoreAttribute
and [ApiMember(ExcludeInSchema = true)]
Should we also support them for exclusions?
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.
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 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.
Both ServiceStack.DataAnnotations and System.ComponentModel.DataAnnotations contain a RequiredAttribute
Should this be supported in addition to the [ApiMember(IsRequired = true)]
?
I noticed you already implemented an extension to support RAML.
Are you planning to support swagger 2.0 as well?
Do you have plans to release a version compatible with ServiceStack >= 5.0.0?
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.
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>
{
....
}
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)
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.
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.
Default the titles to split by camelcase so MyRequest becomes My Request
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)] |
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:
IGateway.Send
method.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.
Related to this commit
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)
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.