Does anyone know how to add custom reference topics to a Sandcastle help file?
I have a .net wcf rest service library and I want to produce reference documentation for the rest API as they are seen from an http client point of view.
For example:
Instead of methods within classes I would like to expose endpoint uris within a service.
Instead of request method parameters I would like them listed in a table indicating if they are query string parameters
For .net dto classes I want them listed in a JSON like fashion.
I know I had to customize some presentation xsl styles in Sandcastle, but first of all I do not know how to add those custom topics and inject the xsl transforms to generate content for those topics, within Sandcastle Help Builder build process?
I know there is support to add conceptual topics, but their content seems targeted to be manually generated and from which you can add references to automatic generated documentation with codeEntityRefferences or am I missing something here?
Related
Supposed you need to interact with/integrate 5+ different web service sources instead of tables from the database.
In first lane each WS supports read methods like search,list and single view (in short, no CUD from CRUD). Write access should also take place later.
What would be your approach to integrate those to extbase?
I'd like to stick to the conventions of models and repositories. In this case, i think we need to use Models and CustomRepositories. Should the repositories interact directly with the webservice or should we think bigger with an PersistenceManagerInterface implementation and extending the Generic/Query to e.g. paginate on the results by extbase conventions? What is about TypeConverters and PropertyMappers for linking between controller actions with the models "as parameters".
How could a mapping from JSON to the models look like? A TCA configuration is required for the DataMapper, but this is not available because no DB is used, so it cannot be used.
Where should you start?
My use case is as follows:
I generate the OpenAPI-compilant specification in json format using SpringFox Swagger2 in my Spring Boot application. During configuration of Docket bean I use its method additionalModels() to add a model that I'd like to document. This model is not explicitly used by any endpoint.
Upon inspection of generated /v2/api-docs as well as swagger-ui.html I can confirm that this model is properly placed under the "definitions" property alongside all other models.
On the other hand ReDoc only seem to render the endpoints and their explicitly used models and responses. Can I somehow force ReDoc to render that one additional class? Like, for example, somehow referencing it in the API description?
I am not sure, but I thinks it's related to this issue. If that's the case and it's not possible at the moment with ReDoc - what would be a reasonable alternative with similar look and feel?
ReDoc author here. This is not yet possible in ReDoc but support for this will be added in the future.
I can't come up with a reasonable workaround at the current stage so stay updated by subscribing to the issue you referenced.
Background
I am developing my first webapi2 rest interface for some products/batches/packs etc. I read this excellent page on how to make a good rest api and i'm stuck on a few concepts and my googling skills have failed me.
I would like to give the developer the option to embed or sideload sub resources to prevent repeated api hits for child/sub-resource data (i.e return all packs with a batch). I would also like them to be able to specify which fields they would like to return.
I'm used to a normal MVC/WebApi style of creating a Method and its own or shared ViewModel and sending down that in its entirety. If I need to send less data I create a slimmer ViewModel.
Question
What return type do I put on the rest endpoint, is it just a JObject that I construct manually depending on what fields they've requested (and the developer has to rely on the documentation to figure out what it could return)?
Or do I create a fat view model and somehow mark the fields as optional with the ability for the JSON/XML converter to omit these fields if the value is null etc (but then how do I side-load sub-resources...)?
Thanks, Pete
I have decided to use OData v4 so that I can allow the client-app to decide on what and how to consume the data i'm exposing. It doesn't support sideloading (that i've discovered so far) but it allows me to embed, filter and slim down any models easily.
It appears most of the WebAPI examples are returning some models (either domain models or particular view models).
When using domain models, we actually request more data than needed in the view from ajax calls, and then build our view models using JavaScript (assuming we are building a web app).
I tried using different view models for each page (view), which allow me to reduce the network footprint and return only the fields in need. But in the ApiController I would have too many GET methods. And it is impossible for us to predict the future need and build an API returning all kinds of view models.
I would like to mimic the Facebook Graph API and build a uri like:
http://... api/games/333?fields=id, name, price, imageUrl
And our user should be able to update the record with only these few fields.
A detailed description can be found in a google code blog entry: Making APIs Faster: Introducing Partial Response and Partial Update.
Some other posts here suggest this is beyond the current ability of ASP.NET WebAPI. Will ServiceStack or some other package help us achieve the goal?
Try this project: https://github.com/AnthonyCarl/ServiceStack.PartialResponse for the partial response side of the question
ServiceStack.PartialResponse.ServiceModel
Google Style Partial
Responses for ServiceStack.Net. Currently only the following Content
types are supported:
application/json
application/jsv
text/html
application/xml is NOT currently supported.
I wanted to implement this as a ServiceStack IPlugin, but I was unable
to figure out how to get the access I needed to the response DTO for
my approach. Currently, this is implemented as an IRequestContext
extension.
Providing Field Selectors
Field Selectors can be passed using the header or query string. By
default field selectors are combined form both. Duplicate field
selectors are reduced. The field selector is applied to all entries in
a list if the selector refers to a list.
There are a couple of options to implementing partial updates in ServiceStack. See this question about implementing PATCH requests for an approach that uses a request DTO with nullable values, and the PopulateWithNonDefaultValues and similar extension methods in ServiceStack, to take a PATCH-style request where the client can send any subset of fields in the request body. If a given field is not present in the request body, then that property of your domain object will not be updated.
If you really need to use a query string to specify the subset of fields that should be updated, then you can still use the approach described above, but add some code that first nulls out any values in the incoming request DTO object that are not named in the query string. Then you can again use PopulateWithNonDefaultValues to copy the remaining values to the domain object.
Also, to comment on another part of your post that is closely related to the recommendations I just gave:
When using domain models, we actually request more data than needed in the view from ajax calls...
Here is where a message-based design is helpful: model your request/response messages as separate DTO classes, instead of reusing and exposing your internal domain model objects. Among over benefits, you'll eliminate the problem of exposing unnecessary fields in your request/response models. Message-based design is one of the core concepts that drives ServiceStack's implementation. You could, though, achieve similar results with Web API or MVC. I highly recommend reading this article that discusses how this design works in ServiceStack.
You can use OData Protocol,look this example.
It's can use key:$select,$expand,$filter for search,select some fileds.
Most important,the ASP.NET WEB API has a SDK for support this.
I added custom metadata through xml configuration specified in their wiki ... I could see the aspect I added in the /share application in manage aspects but it is not listed in /alfresco app and when i am uploading the document using the rest api it says unable to find the field i added ..
Share and old Alfresco Web Client have different configurations.
Check these resources out for more information:
http://wiki.alfresco.com/wiki/Web_Client_Customisation_Guide
http://wiki.alfresco.com/wiki/Displaying_Custom_Metadata
Please read this tutorial which covers creating custom content types and aspects and exposing those to both the Share (/share) and Explorer (/alfresco) web clients.
It sounds like you may have multiple problems, though, beyond configuration, because the REST API should be able to see your custom model, if it is defined correctly, regardless of whether or not it is configured in either of the two web clients.