We are generating API documentation from the source code using Swagger. I am now wondering if there is any tool which automatically checks the compliance of the generated OpenAPI document (= Swagger JSON) to RESTful API design best practices.
For example Zalando has defined a publicly available guideline for REST-design In my opinion in these guideline there are many rules which can be check automatically based on the OpenAPI Specification:
“Don’t Break Backward Compatibility” could be check when OpenAPI
documents of different versions are compared.
“Always Return JSON Object as Top-Level Data Structures to Support
Extensibility"
“Keep URLs Verb-Free” could possible checked if compared with
dictionaries.
…
So far, I only found tools which checks the completeness and naming conventions of an OpenAPI document. Does someone know a tool with more advanced rules?
UPDATE:
Meanwhile I have found a tool called Zally (https://github.com/zalando-incubator/zally). This tool checks for violations of Zalando's REST-Api Guidelines. It is rather easy to configure or extend.
Some of these could be added as rules to openapilint. The backward compatibility check would need to compare two spec versions in search of differences, which is a bit more complex.
Related
I read tons of documentation about pros and cons of URI versioning against Header (media type) versioning (Best practices for API versioning?).
If I want to chose the media type versioning what's the best way to document my API?
I'm using Swagger (2.0) and I looked also into OpenAPI 3.0 but I couldn't find an easy and clear way to exposes different versions for the same endpoint.
I'd like to have a clear and easy understandable way to share my API definitions with my integrators.
I see that in the Microsft managed REST APIs exposed in Azure there are two ways to do versioning
a) x-ms-version in header
b) api-version in query string
I wanted to understand what is the decision behind the selection between the two. I was reading somewhere that x-ms-versioning is legacy and way forward is the query string versioning mode. Is this correct?
Also as per Scot Hanselman's blog he says Query string parameter is not his preferred way and he would choose the URL Path segment. Then wondering why Microsoft adopted this option? I do agree that each person has his own preference but would be helpful to know the reason for this selection from Microsoft.
The x-ms-version header is legacy and only maintained for backward compatibility. In fact, the notion of using the x- prefix has been deprecated since the introduction of RFC 6648 in 2012.
Using api-version in the query string is one of the official conventions outlined in §12 Versioning of the Microsoft REST API Guidelines. The guidelines also allow for using the URL segment method, but the query string method is the most prolific.
Fielding himself has pretty strong opinions about API versioning - namely don't do it. The only universally accepted approach to implementing a versioned REST API is to use media type negotiation. (e.g. accept: application/json;v=1.0 or accept: application/vnd.acme.v1+json). GitHub versions their API this way.
While media type negotiation abides by the REST constraints and isn't all that difficult to implement, it's the least used method. There are likely many explanations for why, but the reality is that there are at least 3 other very common methods: by query string, by URL segment, or by header.
Pedantic musings aside, the most common forms are likely due to the ease in which a client can access the service. The header method is not much different that using media type negotiation. If a header is going to be used, then using the accept and content-type headers with media type negotiation is a better option. This leaves us with just the query string and URL segment approach.
While the URL segment approach is common, it has a few pitfalls that most service authors don't consider. It's proliferation has very much been, "Well, that's how [insert company here] does it". In my opinion, the URL segment method suffers from the following issues:
URLs are not stable. They change over time with each new API version.
As part of the Uniform Interface the URL path is supposed to identify a resource. If your URL paths are api/v1/products/123 and api/v2/products/123, it implies that there are two different products, which is not true. The v1 versus v2 URL segment is implying a different representation. In all API versions, the resource is still the same logical product.
If your API supports HATEOAS, then link generation is a challenge when you have incongruent resource versioning. Mature service taxonomies and the REST constraints themselves are meant to help evolve services and resources over time. It's quite feasible to expect that api/orders could be 1.0 and a referenced line item with api/products/123 support 1.0-3.0. If the version number is baked into the URL, what URL should the service generate? It could assume the same version, but that could be wrong. Any other option is coupling to the related resources and may not be what the client wants. A service cannot know all of the API versions of different resources a client understands. The server should therefore only generate links in the form of vanilla resource identifiers (ex: api/products/123) and let the client specify which API version to use. Any other manipulation by the client of links greatly diminishes the value of supporting HATEOAS. Of course, if everything is the same version or on the same resource, this may be a non-issue.
2 and 3 can be further complicated by a client that persists resource links. When an API version is sunset, any old links to the resource are now broken, even though the resource still exists albeit not using an expected, but obsolete representation.
This brings things full circle to the query string method. While it's true that the query string will vary by API version, it's a parameter not part of the identifier (e.g. path). The URL path stays consistent for clients across all versions. It's also easy for clients to append the query parameter for the version that they understand. API versions are also commonly numeric, date-based, or both. Sometimes they have a status too. The URL api/products/123?api-version=2018-03-10-beta1 is arguably much cleaner than api/2018-03-10-beta1/products/123.
In conclusion, while the query string method may not be the true RESTful method to version a resource, it tends to carry more of the expected traits while remaining easy to consume (which isn't a REST constraint). In conjunction with the Microsoft REST API Guidelines, this is why ASP.NET API Versioning defaults to the query string method out-of-the-box, even though all of these methods are supported.
Hopefully, this provides some useful insights as how different styles can affect your service taxonomy aside from pure preference.
I like the TDD approach to documenting your restful api with spring-rest-docs. However, I love "API Playground" feature enabled by swagger specification. I wish there was a way to get best of both worlds.
Is there a way to build swagger2 specs from spring rest docs? may be via building custom request/response preprocessors.
Do you have any thoughts or recommendations?
There's not out-of-the-box support for this in Spring REST Docs at the moment. The issue that you opened will track the possibility of adding such functionality. In the meantime, your best bet would be to look at writing a custom Snippet implementation that generates (part of) a Swagger specification.
Typically, a Spring REST Docs snippet deals with documentating a single resource, whereas a Swagger specification describes an entire service. This means that the Swagger specification Snippet implementation will need to accumulate state somehow, before producing a complete specification at the end. There are lots of ways to do that (in memory, multiple files that are combined in a post-processing step, etc.). It's not clear to me that one approach is obviously the right one so some experimentation would be useful. If you do some experimentation, please comment on the issue that you opened with your findings.
Spring REST Docs was released recently and the documentation says:
This approach frees you from the limitations imposed by tools like Swagger
So, I wanted to ask when Spring REST Docs is preferable to use comparing to Swagger and which limitations it frees.
I just saw a presentation here that touches on your question among other topics:
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
Swagger doesn't support hypermedia at all / it's URI centric
Swagger's method of inspecting your code can lag behind your code. It's possible make a change in your code that Swagger fails to understand and won't process properly until Swagger gets updated.
Swagger requires lot of annotation, and it's painful to include the descriptive text you want in an api document in annotations.
There are just some things that Swagger can't figure out from inspecting your code.
In any case, these are just a couple of points. The presenter does a much better job discussing it than I could.
I thought I would chime in to give a little bit more context surrounding Swagger, what it is, and what it is not. I believe this might help answer your question.
Swagger 2.0 is being adopted by a lot of big names and big platforms like Microsoft Azure, Paypal, SwaggerHub.com, DynamicApis.com, etc... Something to keep in mind is that Swagger is very simply a specification. It is not a framework. There are a lot of frameworks out there built to generate Swagger output that crawl through your code looking at your API information in order to build the Swagger 2.0 JSON file that represents your API. The Swagger UI that you see your APIs on is driven directly from this Swagger 2.0 JSON file. fiddler it to check it out
It is important to note that a framework that was created to allow you to "use swagger" is not how Swagger has to work (i.e. it is completely up to the implementation of the 3rd party framework). If the framework you are using to generate your Swagger 2.0 documents and UI is not working for you then you should be able to go find another framework that generates the Swagger artifacts and swap the technologies out.
Hope this helps.
From Spring REST docs:
The aim of Spring REST Docs is to help you to produce documentation for your RESTful services that is accurate and readable
This test-driven approach helps to guarantee the accuracy of your service’s documentation. If a snippet is incorrect the test that produces it will fail.
Spring REST docs advantages:
Documentation is written in the test code so it does not overload main code with lots of annotations and descriptions
Generated docs and examples are accurate because related test must pass
Docs can provide more specific and descriptive snippets
Format is suitable for publishing
Spring REST docs disadvantages:
Requires more work
Documentation provides request/response examples but don't provide interactive tools to modify and try out requests
Swagger advantages:
Quick, automated generation from a code
Interactive request execution - can be used for acceptance testing
Built around the OpenAPI Specification
Swagger disadvantages:
For more descriptive documentation it will require a lot of annotations
Tests are not related to the documentation so sometimes documention may deviate from reality
There is some limitation with swagger and the specific spring stack.
For example : with "param" in your Request Mapping you can define more than one method with the same url ans so simplify your code.
But swagger show you just one method
One disadvantage with Swagger is: it cannot handle models which have cyclical dependencies. If a model has cyclical dependency and if swagger is enabled, then spring boot server crashes.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'm writing a specification for a RESTful API for a new internal web service. It's not hugely long and fairly simple, but even so, it's my first time using strict REST (as opposed to cheating for practical reasons - avoiding PUT and DELETE because they're a pain in PHP, and so on). I was wondering if there were any standard methods or best practices for documenting a REST interface? I want the rest of the team to understand it at a glance, and for anyone that wants to write a client to be able to do so without understanding the underlying code.
Sure, REST APIs should ideally use HATEOAS and be hypertext driven (with heavy use of media types), but also having simple human-friendly documentation for developers to work off of is helpful.
Some specific tools that are helpful for generating documentation like this:
Swagger
An open spec for describing REST APIs [ github ]
Tools for auto-generating
Documentation
Code for your API
Donated to the OpenAPI initiative and renamed OpenAPI in 2015
Mashery
An open source project [ github ]
Tools for generating
Documentation
An exploration interface for your API
Apiary and API Blueprint
Write the API description in a DSL within markdown
Tools for auto-generating
Documentation
Mock server
Seems to be focused on ruby+mac devs
RAML
A spec for describing REST APIs [ github ]
WADL
A spec for writing discoverable API docs with XML
Some discussion comparing WSDL and WADL
APIgee
A commercial product with some documentation features
3scale
A commercial product with some documentation features
miredot
Commercial REST API documentation generator
Java specific
I've been using http://apiary.io, which is pretty nice. You can also export the API documentation to github.
In Roy's post here he states
A REST API should spend almost all of
its descriptive effort in defining the
media type(s) used for representing
resources and driving application
state, or in defining extended
relation names and/or
hypertext-enabled mark-up for existing
standard media types. Any effort spent
describing what methods to use on what
URIs of interest should be entirely
defined within the scope of the
processing rules for a media type
(and, in most cases, already defined
by existing media types).
A good ReST documentation would mean documenting your media type and only your media type.
In a typical scenario, you'd produce a document like so:
The Acme Corp XML formats
Link Discovery
Links to various resources are described in a document that can be found by issuing a GET or HEAD request to the server on a bookmark URI (typically the root of the server, http://www.acme.org), and looking for an HTTP Link header:
Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml
where the rel part is the link relationship, and the xxx is the URI for which the relationship has been established.
Link Relationships
This document defines the following relationship names:
http://rel.acme.org/services
The link relationship describes the list of links that can be navigated.
http://rel.acme.org/customers
The link for which this relationship is used is the list of customers.
Media Types
The application/vnd.acme.services+xml is a document with an xml serialization that describes a list of links an application may want to process.
<links>
<link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>
The applcation/vnd.acme.customers+xml is a document with an xml serialization that describes customers.
Example documents:
<customers>
<customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>
etc...
The point is to give a way to the developer to follow the links you define. First find the link to the index so they can get the list of things they can navigate to.
Once they discover that document, they discover that they can see a list of customers at a certain Uri, and can do a GET against it.
If they find a customer of interest, they can follow the link defined in /customers/customer/#href and issue a GET to retrieve a representation of that customer.
From there, your media type could embed actions that are available to the user, using more links. You also have the additional option of issuing an OPTIONS request on the resource to know if you can allow deleting the resource, or a PUT if you can save the document back after modification.
So a good documentation doesn't ever:
give static links
give interaction such as "you can issue POST on Customer with this media type and that will mean the move operation". The client should issue a POST against Customer only because your XML document has specified it that way.
The point of all this is to achieve minimum coupling between clients and servers. The client can be very smart in displaying and discovering resources (showing forms and god knows what else), but is totally dumb as to what the actual workflow is: the server decides.
At my company, we've been very happy using WADL, Web Application Description Language. Wikipedia describes it as: "an XML-based file format that provides a machine-readable description of HTTP-based web applications". I find raw WADL easy to write, read, and understand, and it maps directly to RESTful concepts. The official project provides a simple spec, XSD and RELAX NG schemata, and Java tools.
A number of tools and resources exist for working with WADL, including:
wadl_stylesheets, XSLT stylesheets to create HTML documentation from WADL files
Restlet, a Java framework for building RESTful servers and clients, includes a WADL extension
A tip: try including human-readable documentation, such as descriptions, concepts, getting started, usage tips, etc, in the WADL document's doc element by including HTML elements, using the XHTML namespace. It can make a big difference!
You might find rest-tool useful.
It follows a language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs. It also provides a cook-book however it is in a very early stage, but its content is continuously growing.
The services you just described can be immediately used, so it is also good for experimenting.
Initially, we went for static documentation of resources but just had to field too many questions. Eventually, we moved to using Live documentation pages using IO/Docs (actually a fork).
Been working great.
To create understanding/documentation, heavyweight solutions aren't always needed. Examples of (great) heavyweight tools are: IO/Docs / Apigee (although great tools).
For tiny projects that already have a docchain setup (doxygen/phpdoc/phpdoctor/custom/etc) I use the following shellscript to just include the page in the full generated documentation:
https://gist.github.com/4496972
A demo: http://pastie.org/5657190
It just use custom comment-tags in your sourcecode.
It can also be a nice starting point for documenting any sourcecode (language).