/json-doc

Tool to generate documentation from Java object with json-doc annotations

Primary LanguageJava

json-doc

Json-doc make documenting and maintaining your REST based JSON API easier.

Project Discussions

In additions to the GitHub issues project discussions JsonDoc are on Slack. The group at ChiDev was nice enough to allow us to use a channel in their Slack group. Joining the conversation:

Example Output

Json-doc will scan through a list of classes and create documentation based on included annotations. This way the code can be used as the source for your JSON REST API documentation. This is part of an actual output from the sample application.

++++++++++++++++

A Sample REST Protocol

CreateUserRequest

HTTP method: POST

Path: /createUser

Fields:

Type Name Serialized Name Sample Description
User user user The name, etc. of the user to create
String password password ******** The user's requested password

Sample:

{
  "user": {
    "userName": "chris",
    "firstName": "Chris",
    "lastName": "Wilson",
    "userSince": "Aug 7, 2015 1:36:35 PM"
  },
  "password": "********"
}

User

Fields:

Type Name Serialized Name Sample Description
String userName userName chris The user's userName
String firstName firstName Chris The user's first name
String lastName lastName Wilson The user's last name
Date userSince userSince August 1, 2015 The user's enrollment date

++++++++++++++++

Build Instructions

Prerequisites

You need the following installed and available in your $PATH:

Building

This project requires Java and Maven.

cd code/json-doc/
mvn clean install

Usage

For usage example see the sample project in this repository.

The basic idea is:

  1. Include this in your projects pom.xml:
<dependency>
	<groupId>com.yepher.jsondoc</groupId>
	<artifactId>annotations</artifactId>
	<version>0.0.2</version>
</dependency>
<dependency>
	<groupId>com.yepher.jsondoc</groupId>
	<artifactId>documentor</artifactId>
	<version>0.0.2</version>
</dependency>
  1. Annotate your classes with these annotations RequestPDU, ResponsePDU and Description

Example:

import lombok.Data;
import lombok.EqualsAndHashCode;

@Data
@EqualsAndHashCode(callSuper=true)
@ResponsePDU(request={CreateUserRequest.class})
public class CreateUserResponse extends ResponseBase {

    @Description(value="The user's authorizationtoken (in Base64)",sample={"0123456789abcdefghi","zyxwvutsr9876543210"})
    public String authorizationToken;

}
  1. Create a class that extends ClassListDriverBase. This class tells Documentor which classes should be documented:

Example:

public class ClassListDriver extends ClassListDriverBase {

    ClassListDriver() {
        super();
    }


    private static final String TITLE = "A Sample REST Protocol";

    /* @formatter:off */
    private List<Class<?>>      pdusToDocument = new ArrayList<Class<?>>(Arrays.asList(
                CreateUserRequest.class,
                CreateUserResponse.class
            ));

    private Set<Class<?>>       pdusToExclude = new HashSet<Class<?>>(Arrays.asList(
                Date.class
            ));
    /* @formatter:on */

    private String              outputPath     = "doc/sample1/protocol.md";

    @Override
    protected String getOutputPath() {
        return outputPath;
    }

    @Override
    protected void setOutputPath(String outputPath) {
        this.outputPath = outputPath;
    }

    @Override
    protected String getTitle() {
        return TITLE;
    }

    @Override
    protected List<Class<?>> getPdusToDocument() {
        return pdusToDocument;
    }

    @Override
    protected Set<Class<?>> getPdusToExclude() {
        return pdusToExclude;
    }

    @Override
    public void addPduToDocument(Class<?> clazz) {
        List<Class<?>> pdusToDocument2 = getPdusToDocument();
        if (!pdusToDocument2.contains(clazz) && !getPdusToExclude().contains(clazz)) {
            pdusToDocument2.add(clazz);
        }
    }

    public static void main(String[] args) throws Exception {
        new ClassListDriver().run(args);
    }

}

Goals

Release Stuff:

Related Projects