Как я могу создать документацию для моего Джерси REST API, который использует привязку JSON JAXB?

Question

Теперь, когда я выяснил how to use JAXB generate JSON, я могу запросить/ответить на него на моем сервере, и я хотел бы выяснить, как я могу создать полезную документацию для людей, которые не используют Java. Код моего сервера выглядит так:

@POST 
@Path("apath") 
@Consumes(MediaType.APPLICATION_JSON) 
public String postAPath(InstanceWithXmlRootElementAnnotation instanceWithXmlRootElementAnnotation) { 

Это все хорошо, если кто-то использует Java. Я просто даю им Jar с классом InstanceWithXmlRootElementAnnotation и расскажу им, чтобы отправить его (да, есть немного больше работы, игнорируйте эти детали).

Если они используют какой-либо другой язык, я не знаю, как я должен сообщать им формат своей полезной нагрузки и что ожидать от сервера, если он возвращает InstanceWithXmlRootElementAnnotation. Как я могу создать документацию, которая объясняет ожидаемый формат полезной нагрузки JSON?

Answer 1

Форс является хорошим вариантом (в @fehguy), и вы должны также проверить enunciate и посмотреть, что работает лучше всего для вашего приложения ...

Answer 2

Да, это как раз то, что для Swagger. Посмотрите на github для получения подробной информации о том, как это интегрируется с JAX-RS

Answer 3

Также попробуйте излагает, он разбирает JavaDoc и JAX-RS аннотации ваших классов обслуживания для создания документации:

http://enunciate.codehaus.org/

Вот несколько примеров документации генерируется излагают:

https://repository.sonatype.org/nexus-restlet1x-plugin/default/docs/index.html

Существует плагин maven, который хорошо работает. Он также создает клиентские библиотеки на разных языках, а также образец xml для служб на основе xml. Теперь он поддерживает документацию по swagger.

Answer 4

Кураж использует аннотацию, которые могли бы получить спутать с другими функциональными аннотациями ..

Используйте APIDOC для создания этого прекрасного разделения между функциональными аннотациями и документацией. Это выглядит как нормальная документация над каждым методом. например:

/** 
* @api {get} /user/:id Request User information 
* @apiName GetUser 
* @apiGroup User 
* 
* @apiParam {Number} id Users unique ID. 
* 
* @apiSuccess {String} firstname Firstname of the User. 
* @apiSuccess {String} lastname Lastname of the User. 
*/