Skip to content

Instantly share code, notes, and snippets.

@Aldaviva

Aldaviva/QuotesResource.java

Created September 8, 2013 17:11
Show Gist options
  • Save Aldaviva/6486545 to your computer and use it in GitHub Desktop.
Save Aldaviva/6486545 to your computer and use it in GitHub Desktop.
Download ZIP
JAX-RS API documentation generation from Javadoc using Aldaviva/harbor. Build with "mvn site"
Raw
QuotesResource.java
package vc.bjn.quotes.api.resource;
import vc.bjn.quotes.data.entity.Quote;
import vc.bjn.quotes.data.repo.QuotesRepository;
import vc.bjn.quotes.data.repo.Repository;
import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
/**
* Holy crap it's a quotes page
*/
@Path("/quotes//")
@Component
public class QuotesResource extends AbstractApiResource<Quote, Long> {
@Autowired private QuotesRepository quotesRepository;
@Override
protected Class<Quote> getEntityClass() {
return Quote.class;
}
@Override
protected Repository<Quote, Long> getRepository() {
return quotesRepository;
}
/**
* Show me the quotes.
* @return all quotes in an unspecified order
* @example <code>[{ "id":123, "author":"Somebody", "body":"Something funny", "date":1378658316829, "votes":1 }]</code>
* @example <code>[]</code>
*/
@Override
@GET
public Iterable<Quote> listAll() {
return super.listAll();
}
/**
* @param id the id of the quote to get
* @example 123
* @return quote with the specified id
* @example <code>{ "id":123, "author":"Somebody", "body":"Something funny", "date":1378658316829, "votes":1 }</code>
* @exception 404 if no quote is found with the specified id
*/
@Override
@GET
@Path("/{id}")
public Quote get(@PathParam("id") final Long id) {
return super.get(id);
}
/**
* Make a new quote.
* @param entity fields to set on the new quote (omit the id, it will generated by the server)
* @example <code>{ "author":"Me", "body":"A solid joke", "date":1378658399457 }</code>
* @return the created quote, with a generated id
* @example <code>{ "id":123, "author":"Me", "body":"A solid joke", "date":1378658399457, "votes":0 }</code>
*/
@Override
@POST
public Quote insert(final Quote entity) {
entity.setVotes(0);
return super.insert(entity);
}
/**
* Full update of a quote.
* @param id the id of the quote to update
* @param entity the fields to overwrite the quote with. Any fields missing from the request, except id, will be set to <code>null</code> on the quote.
* @return the modified quote with all fields represented
* @exception 404 if the quote does not already exist (create it with a POST)
*/
@Override
@PUT
@Path("/{id}//")
public Quote updateAllFields(@PathParam("id") final Long id, final Quote entity) {
return super.updateAllFields(id, entity);
}
/**
* Remove a quote.
* @param id the id of the quote to remove
* @return 204
*/
@Override
@DELETE
@Path("///{id}")
public void delete(@PathParam("id") final Long id) {
super.delete(id);
}
}
Raw
resources.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Resources</title>
</head>
<body>
<ul class="resources">
<li class="resource">
<h2>quotes/*</h2>
<div class="description">Holy crap it's a quotes page</div>
<ul class="methods">
<li class="method">
<span class="verb">GET</span>
<span class="path">quotes</span>
<div class="description">Show me the quotes.</div>
<div class="outputs">
<div class="contentType">application/json</div>
<div class="type">Iterable</div>
<div class="description">all quotes in an unspecified order</div>
<div class="examples">
<div class="example">
<span><code>[{ "id":123, "author":"Somebody", "body":"Something funny", "date":1378658316829, "votes":1 }]</code></span>
</div><div class="example">
<span><code>[]</code></span>
</div>
</div>
</div>
</li><li class="method">
<span class="verb">GET</span>
<span class="path">quotes/{id}</span>
<div class="description"></div>
<div class="inputs">
<div class="arguments">
<div class="argument">
<span class="type">Long</span>
<span class="name">id</span>
<span class="location">PATH</span>
<div class="description">the id of the quote to get</div>
<div class="examples">
<div class="example">
<span>123</span>
</div>
</div>
</div>
</div>
</div>
<div class="outputs">
<div class="contentType">application/json</div>
<div class="type">Quote</div>
<div class="description">quote with the specified id</div>
<div class="examples">
<div class="example">
<span><code>{ "id":123, "author":"Somebody", "body":"Something funny", "date":1378658316829, "votes":1 }</code></span>
</div>
</div>
</div>
</li><li class="method">
<span class="verb">POST</span>
<span class="path">quotes</span>
<div class="description">Make a new quote.</div>
<div class="inputs">
<div class="contentType">application/json</div>
<div class="arguments">
<div class="argument">
<span class="type">Quote</span>
<span class="name">entity</span>
<span class="location">BODY</span>
<div class="description">fields to set on the new quote (omit the id, it will generated by the server)</div>
<div class="examples">
<div class="example">
<span><code>{ "author":"Me", "body":"A solid joke", "date":1378658399457 }</code></span>
</div>
</div>
</div>
</div>
</div>
<div class="outputs">
<div class="contentType">application/json</div>
<div class="type">Quote</div>
<div class="description">the created quote, with a generated id</div>
<div class="examples">
<div class="example">
<span><code>{ "id":123, "author":"Me", "body":"A solid joke", "date":1378658399457, "votes":0 }</code></span>
</div>
</div>
</div>
</li><li class="method">
<span class="verb">PUT</span>
<span class="path">quotes/{id}</span>
<div class="description">Full update of a quote.</div>
<div class="inputs">
<div class="contentType">application/json</div>
<div class="arguments">
<div class="argument">
<span class="type">Long</span>
<span class="name">id</span>
<span class="location">PATH</span>
<div class="description">the id of the quote to update</div>
</div><div class="argument">
<span class="type">Quote</span>
<span class="name">entity</span>
<span class="location">BODY</span>
<div class="description">the fields to overwrite the quote with. Any fields missing from the request, except id, will be set to <code>null</code> on the quote.</div>
</div>
</div>
</div>
<div class="outputs">
<div class="contentType">application/json</div>
<div class="type">Quote</div>
<div class="description">the modified quote with all fields represented</div>
</div>
</li><li class="method">
<span class="verb">DELETE</span>
<span class="path">quotes/{id}</span>
<div class="description">Remove a quote.</div>
<div class="inputs">
<div class="arguments">
<div class="argument">
<span class="type">Long</span>
<span class="name">id</span>
<span class="location">PATH</span>
<div class="description">the id of the quote to remove</div>
</div>
</div>
</div>
<div class="outputs">
<div class="description">204</div>
</div>
</li>
</ul>
</li>
</ul>
</body>
</html>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment