How to document models & services which are in a separate project

Question

I'm looking to demonstrate ServiceStack to my team, and as part of the demo I want to create some documentation. The UseCases.SwaggerHelloWorld runs fine, but my project (which has 1 functioning service) returns an empty swagger page. When I visit /resources it returns:

{
  "swaggerVersion":"1.2",
  "apis":[],
  "apiVersion":"1.0",
  "basePath":"http://localhost:29672",
  "info":{"title":"Reports.Api"}
}

I then copied the Hello* service and models into my API project (in the same assembly as the host) and this worked. I then moved the service and models out into separate projects and the docs disappeared again.

So my question is, how can you document APIs when the models are in a separate DLL? The project structure is the same as recommended when you create a solution using the servicestack solution template.

score 0 · Accepted Answer · edited May 23 '17 at 12:14

0

The AppHost constructor tells ServiceStack which assemblies it should scan to locate, register and auto-wire your Services, e.g:

public class AppHost : AppHostBase
{
    public AppHost() : base("Hello App", typeof(HelloService).Assembly) {}
}

It supports specifying multiple Assemblies if your Services are maintained in different projects, e.g:

public class AppHost : AppHostBase
{
    public AppHost() : base("Hello App", 
        typeof(HelloService).Assembly, typeof(OtherService).Assembly) {}
}

The Modularizing Services docs has more info.

The DTO's used by the Service can be in a different project, you just need to specify which assemblies the Services are in. Although it's recommended the DTO's are maintained in a separate dep-free project which is the recommended Physical Project Structure that's contained in each ServiceStackVS VS.NET Project Template.

edited May 23 '17 at 12:14

Community

1
1

answered Oct 06 '15 at 13:15

mythz

141,670
29
246
390

Thanks for the reply. Useful stuff, but I probably didn't make it clear. I have registered and auto-wired services as above, and configured AppHost to reference the other assembly. All is working and metadata returns these services / routes etc. It is just swagger doesn't work. The JSON returned at /resources returns empty. If I move all code into the host project, swagger works fine, as per the sample app. So how do I tell swagger where to find the services / models when they live in a different assembly and/or namespace? – Neil Dobson Oct 06 '15 at 22:55
...in other words how do I influence how /resources is being built, at it is not working correctly for me. – Neil Dobson Oct 06 '15 at 22:57
1

@NeilDobson I've done what you said with the SwaggerHelloWorld project [in this commit](https://github.com/ServiceStack/ServiceStack.UseCases/commit/de14dcf430f454f1dfdf556487b9886817d51a31) and split Services across into a [new project](https://github.com/ServiceStack/ServiceStack.UseCases/commit/f9e58cea0e52218847997a17dc7a39b5180176bd), Swagger still works whether I reference 1 or both assemblies. Can you submit a pull-request that exhibits the issue you're seeing? – mythz Oct 06 '15 at 23:07
Thanks @mythz After some tinkering I found the problem. I have a route of [Route("/{AgencyKey}/carerCriminalCheck/", Summary = "Carer Criminal Check Report")]. This is a multi-tenancy system and I wanted to demonstrate all routes are prefixed with key. Later will change this so key is part of auth. Anyway once I changed route to /carerCriminalCheck/{AgencyKey} the service appeared in swagger. So I guess something is a bit picky about the routing. Anyway, all good now. Thanks. – Neil Dobson Oct 07 '15 at 11:08
@NeilDobson yeah only the [Fallback Route](https://github.com/ServiceStack/ServiceStack/wiki/Routing#fallback-route) can start with a non-literal route. – mythz Oct 07 '15 at 11:22

How to document models & services which are in a separate project

1 Answers1