64

I have written a pretty extensive REST API using Java Jersey (and JAXB). I have also written the documentation using a Wiki, but its been a totally manual process, which is very error-prone, especially when we need to make modifications, people tend to forget to update the wiki.

From looking around, most other REST API's are also manually creating their documentation. But I'm wondering if theres maybe a good solution to this.

The kind of things which need to be documented for each endpoint are:

  • Service Name
  • Category
  • URI
  • Parameter
  • Parameter Types
  • Response Types
  • Response Type Schema (XSD)
  • Sample requests and responses
  • Request type (Get/Put/Post/Delete)
  • Description
  • Error codes which may be returned

And then of course there are some general things which are global such as

  • Security
  • Overview of REST
  • Error handling
  • Etc

These general things are fine to describe once and don't need to be automated, but for the web service methods themselves it seems highly desirable to automate it.

I've thought of maybe using annotations, and writing a small program which generates XML, and then an XSLT which should generate the actual documentation in HTML. Does it make more sense to use custom XDoclet?

Cœur
  • 37,241
  • 25
  • 195
  • 267
Alan Mc Kernan
  • 763
  • 1
  • 6
  • 7
  • 3
    Enunciate.codehaus.org pulls the documentation from the Javadocs: it's open source and works with Jersey, so maybe you could look into that? – Tim Nov 11 '09 at 09:28
  • possible duplicate of [RESTful API Documentation](http://stackoverflow.com/questions/1966243/restful-api-documentation) – cHao Nov 01 '11 at 00:21
  • 1
    I have been using enunciate for a few years now and it has some quirks. It doesn't handle custom types so well and gets utterly confused with abstract dtos. Infact, I am on this post right now looking for its replacement – Christian Bongiorno May 20 '13 at 17:59

7 Answers7

42

Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.

Integration guide: https://github.com/swagger-api/swagger-core/wiki

More Information: http://swagger.io/

enter image description here

Marcio Aguiar
  • 14,231
  • 6
  • 39
  • 42
Ben
  • 60,438
  • 111
  • 314
  • 488
22

Unfortunately, Darrel's answer is technically correct, but is hocus-pocus in the real world. It's based on the ideal that only some agree on and even if you were very careful about it, the chances are that for some reason outside your control, you can't conform exactly.

Even if you could, other developers that might have to use your API may not care or know the details of RESTful patterns... Remember that the point of creating the API is to make it easy for others to use it and good documentation is a must.

Achim's point about the WADL is good however. Because it exists, we should be able to create a basic tool for generating documentation of the API.

Some folks have taken this route, and an XSL stylesheet has been developed to do the transform: https://wadl.dev.java.net/

Brill Pappin
  • 4,692
  • 1
  • 36
  • 36
  • 1
    Could you point me to the documentation that showed the web browser developers how to access the information on stackoverflow.com? Or are those guys not part of the real world? – Darrel Miller May 20 '10 at 21:40
  • 2
    No need to pick a fight Darrel. I have no idea what the stack overflow folks have set up in terms of an API and I don't much care because I have no need of it. If they don't provide documentation for their API then I feel sorry for the person who has to integrate. – Brill Pappin May 13 '11 at 15:26
  • 2
    There was no aggression intended. I also am not referring to the Stackoverflow API. I'm referring to the web site. The web site works over HTTP and is consumed by a client application called a "web browser". My point is that when you build a web site, you don't need to call Google to tell them how to adapt Chrome so that it can consume your web site. By using well documented media types, there is no need for "API" document. – Darrel Miller May 14 '11 at 01:18
  • 8
    Chrome is controlled by a human operator. Most API clients are automatic. If you wanted to navigate `Stackoverflow.com` with a robot you would need intimate knowledge about the structure and expected use of the site. You would not "explore it from a root URL" nor expect the media type of "text/html" provide much help. You'd end up exploring it by hand to create just the kind of map a good API documentation provides. – Alexander Ljungberg Sep 20 '12 at 14:15
  • 4
    The stackoverflow API has great documentation (see https://api.stackexchange.com/docs ) this notion of not documenting a ReSTful API is ridiculous in the real world and does not in any way help answer the original question. – Randyaa Aug 06 '13 at 13:20
16

Although i'm not sure it will totally fit your needs, take a look at enunciate. It seems like a good documentation generator for various web-services architectures.

EDIT Enunciate is available under github umbrella

Riduidel
  • 22,052
  • 14
  • 85
  • 185
8

you might be interested in Jersey's ability to provide so called WADL description for all published resources in XML format at runtime (generated automatically from annotations). This should be containing already what you need for basic documentation. Further you might be able to add additional JavaDoc, though that requires more configuration.

Please look here: https://jersey.java.net/documentation/latest/wadl.html

kmonsoor
  • 7,600
  • 7
  • 41
  • 55
2

Darrel's answer is exactly right. The kind of description must not be given to clients of a REST API because it will lead the client developer to couple the implementation of the client to the current implementation of the service. This is what REST's hypermedia constraint aims to avoid.

You might still develop an API that is described that way, but you should be aware that the resulting system will not implement the REST architectural style and will therefore not have the properties (esp. evolvability) guaranteed by REST.

Your interface might still be a better solution than RPC for example. But be aware what it is that you are building.

Jan

Jan Algermissen
  • 4,930
  • 4
  • 26
  • 39
0

You might find rest-tool useful. It follows language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs.

You can use it only for documenting your APIs, but this specification can immediately be used to quality assure the implementation of the real services.

If your services are not fully implemented yet, but for example should be used by a web frontend application, rest-tool provides instant mocking based on the service description. content schema validation (JSON schema) also can be easily added beside the documentation as well as used by the unit tests.

tombenke
  • 91
  • 2
-2

I hate to be the bearer of bad news, but if you feel the need to document the things you listed, then you probably did not create a REST interface.

REST interfaces are documented by identifying a single root URL and then by describing the media type of the representation that is returned from that URL and all the media types that can be accessed via links in that representation.

What media types are you using?

Also, put a link to RFC2616 in your docs. That should explain to any consumer how to interact with your service.

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • 3
    Well, you would probably still want to provide a documentation for the different routes you have, right? – Cem Catikkas Nov 12 '09 at 00:57
  • Depends what you mean by routes. From the client's perspective it needs to understand from the description of the media type what links it can follow. If that is what you mean by routes, then yes. However, if by routes you mean what URLs the server exposes then no, that should not be included in documentation for the client. – Darrel Miller Nov 12 '09 at 01:52
  • If you you are going to downvote you really should have the guts to justify it. – Darrel Miller Nov 12 '09 at 15:13
  • 3
    If you are referring to that Discovery will be enough documentation for a REST interface, then your either bad at writing API's or you are writing very small and easy digestible services. I would say that it is hard to auto generate good documentation for API's as you need to think in terms of USER GOALS and there in the workflow. Mostly we think in terms of "What can my API do, What can my particular Resource do", and not in terms of "What does the user want to do?"... REST leverages a little of this by allowing you to tell "What you can do from here", but that may not be enough. – Jens Oct 20 '11 at 14:49
  • @Jens ...or when I write clients, I do not make any assumptions about what resources exist on the server. The same way a web browser makes no assumptions about which web pages exist. – Darrel Miller Oct 20 '11 at 14:57
  • Documenting Workflows and end user goals does not have to be explicit about where the resources are located. It's about telling the user "How he/she makes a purchase" because that is his/hers intent, goal. Instead of telling him/her "How you add an item to your basket (which happens to be a document of some sort)" in isolation, you may in such documentation have to make it apparent to the user that he/she will be told during the steps where to go next.. – Jens Oct 20 '11 at 15:26
  • @Jens Media type documentation, or an application level semantic profile http://amundsen.com/hypermedia/profiles/ should be used for describing user workflow. – Darrel Miller Oct 20 '11 at 20:04
  • Just to be clear, when you refer to Media type that would be what we used to refer to as MIME type? If so I disagree. We don't tend to do these things because we don't think of developers like we think of the general users, but we should. An application level semantic profile might be conceptually what I am looking for, I could see they talked about advancing the state of a resource, then yes, but you never argued that before. But the example is an awful one then. Problem is that we often think that our interfaces is obvious and apparent to other developers instantly, they never are. – Jens Oct 21 '11 at 08:02
  • 16
    This is silly. A REST API is just that, an API. There's no way to write a generic client that knows how to interact with every REST API, no matter how self-documenting they are. A client will have some knowledge of the API baked-in, and generating documentation to describe that API seems sane. – Ted Mielczarek Oct 08 '12 at 19:26
  • 4
    @Ted Can you show me the documentation that the web browsers developers used when building support for the StackOverflow website? And before you come back with "but web browsers are different". Ask yourself, why are they different. They are native applications that consume the HTML/CSS/jpeg/png media types from an HTTP server that exposes resources. – Darrel Miller Oct 08 '12 at 19:33
  • 4
    @Darrel Chrome *works* because of standards and it just renders. It does not interact with a service unless told to do so, and even then, the user has to give it exact instructions and the URI for Chrome to perform the interaction. It's not magic. Most REST clients have custom interaction and customer rendering schemes based on the structure of the response data. I have no idea how you get by without documentation unless you're the only consumer. Instead of talking about browsers and the web, show me real world REST services that have zero documentation that are easy to write clients for. – Lo-Tan Oct 09 '12 at 19:58
  • Seriously? You'd create a cryptic service then tell the consumer to RTFM?! – Nate Dec 12 '12 at 15:32
  • @Nate I'm not sure where I suggested that people should create cryptic services. Regarding reading the HTTP spec, yes I think everyone using HTTP should read the spec. – Darrel Miller Dec 12 '12 at 16:21
  • 3
    @Nate I HATE these sort of answers. Documentation is not just for developers. I cannot hand my salesperson the RFC spec on HTTP and ask them to have their prospects figure it out themselves. Ah, you've been doing software for 20+ years - it all makes sense now... – tpow Jul 03 '13 at 22:06
  • @tpow Does this documentation make sense to you? http://amundsen.com/hypermedia/profiles/ – Darrel Miller Jul 03 '13 at 22:41
  • 3
    @DarrelMiller is talking about HATEOAS: the idea that a RESTful document should contain links enumerating all the possible 'next steps' or 'related items'. This makes sense for HTML because we want our browsers to display links on a page so we can navigate just by clicking, rather than by continually typing new URLs into the URL box. For a RESTful API though this doesn't make as much sense: an automated client needs to know something about the service it's talking to, and it's not unreasonable to require the client to compose the URLs it needs. – Michael Iles Jan 16 '14 at 14:37
  • @michael.iles. You are correct, it is not unreasonable to require the client to compose URLS. However, that would not be a RESTful system, as RESTful systems must be hypertext driven. RESTful clients MUST not take dependencies on the server's resource structure. – Darrel Miller Jan 17 '14 at 12:22
  • 6
    @DarrelMiller According to Roy Fielding (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) you're right that RESTful systems must be hypertext-driven. However I think this is an extreme position and that there is a large and productive class of APIs that embrace HTTP and emphasize nouns, media types, statelessness, document versioning, etc., but do away with HATEOAS and allow clients to build their own URLs... and that this is what most people would colloquially refer to as 'REST' these days. It would be great if we had a new term for it. – Michael Iles Jan 29 '14 at 20:55
  • 2
    @MichaelIles A number of us simply refer to those as HTTP Apis. It is unfortunately that there are not more publicly visible hypermedia driven APIs. I don't think it would take you long to see that they are not nearly as "extreme" as they are perceived and are actually very effective in real practical scenarios. – Darrel Miller Jan 29 '14 at 21:36
  • 3
    This is an unproductive, pipe dream answer, more suitable for philosophical discussion than Stack Overflow. That discussion would be interesting, mind you, but here it's just proselytizing. – DavidS Dec 14 '15 at 21:34
  • 2
    This answer is pie-in-the-sky nonsense that uses a pedantic definition of a REST service and is totally out of touch with reality in regards how REST is used in the real world. – Michael Sep 05 '17 at 16:03
  • @Michael Just curious, have you ever tried using an API that is documented this way? I have also done work with the OpenAPI way of describing APIs, so I've worked with both approaches. – Darrel Miller Sep 05 '17 at 17:37
  • @DarrelMiller I have honestly never seen a service that uses the HATEOAS principle in the wild, I suspect this is because very few use cases lends itself to that principle. Sure what most people call REST these days is a hybrid of RPC and REST, but that is because this is what evolved based on real world usage and not pure academia. OPs question was based on this hybrid approach. – Michael Sep 06 '17 at 15:34
  • 1
    @Michael You've never seen hypermedia used "in the wild", you think "very few use cases", "pie-in-the-sky nonsense", "out of touch with reality", "pure academia". All statements typed into a native application, driven by a hypermedia media type and making HTTP based API calls to a remote HTTP origin server. Those trees are a forest. – Darrel Miller Sep 06 '17 at 17:25