In ASP.NET Core or Classic ASP.NET we can use Swashbuckle to Generate beautiful API documentation, including a UI to explore and test operations, directly from your routes, controllers and models.
I have different user case. I already have swagger .json file (version 2.0). I want to load that file into Swashbuckle, and can Swashbuckle return Swagger UI HTML as string?
Once i get string, i am going to use it somewhere else in down the line process
Swashbuckle just uses SwaggerUI which is open source. You can just use SwaggerUI directly.
SwaggerUI
You can also use something like this to visualize your Swagger.
Swagger Editor
Related
Using django-rest-framework-json-api I am able to create API end points that work as described within the documentation. Attempted to provide API documentation using django-rest-swagger is not so easy.
1: Swagger uses media_type = 'application/json' which is not supported in the JSON API. To get around this I created a second render class (renderer_classes) that sub classes the JSON API JSONRenderer and forces the media type.
Now the end point supports application/json and application/vnd.api+json and swagger is happy to render in JSON API document structure. Aware that the generated curl requests have none a standard JSON API header.
2: Swagger has the same issue with the parser. While the work out from issue 1 does work there is a secondary challenge. Swagger renders a flat dictionary of field names which is not JSON API and ultimately is requested by DRF.
Is it possible to get swagger to parse in JSON API? At the moment Swagger is not working for PUT or POST.
djangorestframework-jsonapi==2.2.0
djangorestframework==3.5.4
Django==1.11.2
coreapi==2.3.1
python 3.6
Answering my own question here so that others can gain value from what was learnt. We never found a solution to this issue and we did not have the time available to contribute to this project. In general the project also appears to be struggling, maybe due to people like us not contributing...
An alternative project drf-yasg has now emerged, which did not exist at the time of this original posting. drf-yasg was relatively easy to deploy and solved all of our issues so we have now migrated to this project instead.
So if you a looking for swagger api documentation for JSON API endpoints created within DRF, then I would suggest drf-yasg.
At the time of writing JSON API is not supported out of the box, but there is sample code to get it up and running relatively easily. With this change in place, all of the endpoints will be auto documented.
This Github Gist that contains the code from our app, hope that this helps you out until this feature is fully developed.
As you pointed out in your own answer there is an alternative: drf-yasg. This is great package but does not support JSON API schema out of the box.
That's way you'd even better use drf-yasg-json-api that adds JSON API support to drf-yasg by providing all necessary field inspectors, you just need to slightly extend your SWAGGER_SETTINGS.
Check drf-yasg-json-api Github repo for details.
Disclaimer: I am the author of this package.
We are using Swashbuckle to generate the swagger output for the REST endpoints of our MVC api application. I'm wondering what options there are for unit testing the swagger in a test project. I want to verify things like method names, descriptions, parameters etc etc to minimize the possibility that breaking changes can be introduced.
Thanks,
Please try Swagger-Codegen, which is a free an open source project to automatically generate API clients, server stubs and API documnetation.
For the C# API client generated by Swagger Codegen, it comes with test files for unit testing and you can update it to detect breaking changes by reusing the same tests after updating the OpenAPI/Swagger Spec files.
I'm building an flask application that makes resources available via an restful API and the Web. Both parts of the app use the same models/business logic. The URL (/api/) and the request type should determine which part handles each request.
What is the best way to achieve this with flask? The error messages (e.g. 404 or 500) should have the right content type (html or json).
Can I use the flask-restful extention (together with render_html etc.) or do I have to use 2 parallel apps?
Two parallel apps can be easy to work and scale but you can do it in one single app. Create blueprints for each module of your app (api, auth, etc...) just return json for api and render template for web. In case of errors you need to create error handlers for each blueprint (errors for API should return JSON and web should return HTML pages).
The idea is to call a method from a website(in php) to my application (in Grails). The application will serve data in json format.
The website and the application are hosted in two different servers. The website is on Yahoo and the application is on Rackspace.
Now, I want to create a web service in my Grails application which serves list of cities in json format.
City Class
class City {
String name
String code
}
How do i write the web service method?
Try the grails jaxrs plugin (https://github.com/krasserm/grails-jaxrs) which will do excactly what you want without any hassle.
Simply install it, create a Resource object with the introduced create-resource command and create and annotate the methods as you wish. all other things are managed by the plugin so you don't have to worry about Controller or UrlMapping...
You need only the annotation #Resource(uri='/cities') on your domain and call the url/cities.json (but, its'n RESTful)
You will want to use a few tools, first you will create a controller that deals with the requests and pushes them off to your service layer.
You can use URL Mappings to make it more RESTFul check out the doc that way all the http methods will be mapped to actions in your controller.
Also if you will be doing a fair bit of json I would recomend starting with the gson plugin it has a fuller feature set then the built in JSON support.
The link from the comment above is a great resource to read as well.
I have found that I most of the time want to support the accept header as well in which case you will need to update your config with the following code. See withFormat doc for more info.
grails.mime.use.accept.header = true
Is it possible to develop Restful services for GET,PUT, POST and DELETE using an XML file as data source? I am using Netbeans 6.5.1 . Any references which I could use?
Sure, you can. You need to create a REST controller with the different REST methods (anotated with #GET, POST, ...). These methods will need to access the xml file. You should have a dedicated class for managing the file (with CRUD operations, etc.).
I think you can automatically generate your web service skeleton with netbeans but as it's not my IDE I am not sure. Anyway writing a REST resource is very simple. Look for Jersey examples as I guess you will select this library.