[
https://issues.apache.org/jira/browse/TIKA-1269?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13968296#comment-13968296
]
Sergey Beryozkin commented on TIKA-1269:
----------------------------------------
Hi Lewis, thanks for the comments,
First of all, here are few more links:
http://tools.ietf.org/html/draft-nottingham-json-home-02
and
http://www.restdoc.org/spec.html
Both support JSON to describe the services. IMHO it can be tricky to turn it to
HTML.
If I were to choose, I'd go for either Enunciate or WADL. I don't have the
experience with the former, I should've really had some, I know it requires a
bit of customizations and people who have done it seem to be happy. The reason
I like WADL is that, in addition to being the most complete language IMHO, it
is also, being XML, can be easily turned into HTML. For example, Apache
Syncope uses this approach.
As a side note, my favourite style is:
https://dev.twitter.com/docs/api/1.1
I think WADL can support it.
As far as CXF is concerned: it can auto-generate WADL or have a prepared WADL
registered; the work on Java to WADL generation at the build time is in
progress. The prepared WADL style might be preferred because Tika Server API is
not rich in a sense that it has no grammars/schemas available, it is fairly
simple at this stage and as such it can be difficult to create a descriptive
document.
That said, I'm fine if the other approach gets chosen; I don't have experience
with Enunciate but hopefully someone else does :-).
I'm also open to getting CXF itself further enhanced to support different
approaches, and right now I'm leaning toward JSON home as I know it has some
traction in the community... CXF also optionally supports Swagger but it
requires few Scala dependencies...
Cheers, Sergey
> Self-hosted documentation for the JAX-RS Server
> -----------------------------------------------
>
> Key: TIKA-1269
> URL: https://issues.apache.org/jira/browse/TIKA-1269
> Project: Tika
> Issue Type: Improvement
> Components: server
> Affects Versions: 1.5
> Reporter: Nick Burch
> Fix For: 1.6
>
> Attachments: enable-enunciate.patch
>
>
> Currently, if you fire up the JAX-RS Tika Server, and go to the root of the
> server in a web browser, you get an empty page back. You have to know to head
> over to https://wiki.apache.org/tika/TikaJAXRS find out what the available
> URLs are
> We should self-host some simple documentation on the server at the root of
> it, so that people can discover what it offers. Ideally, this should be
> largely auto-generated based on the endpoints, so that we don't risk missing
> things when we add new features
> This will also allow us to potentially offer a sample running version of the
> server for people to discover Tika with
--
This message was sent by Atlassian JIRA
(v6.2#6252)
