JSONDoc

easily generate docs and playground for your RESTful API

Contacts

Email StackOverflow


Annotation to document global data

If your api has the same behavior across the whole application, you can inform your api users using the ApiGlobal annotation. Let's see how with an example:

package org.jsondoc.sample.global;

import org.jsondoc.core.annotation.global.ApiGlobal;
import org.jsondoc.core.annotation.global.ApiGlobalSection;

@ApiGlobal(
	sections = { 
		@ApiGlobalSection(
			title = "HTTP Verbs", 
			paragraphs = { 
				"This is to demonstrate the use of paragraphs",
			 	"/jsondocfile:/jsondoc/global-verbs.html"
			 }
		),
		@ApiGlobalSection(
			title = "Authentication",
			paragraphs = { "/jsondocfile:/jsondoc/global-authentication.html" }
		),
		@ApiGlobalSection(
			title = "Headers",
			paragraphs = { "/jsondocfile:/jsondoc/global-headers.html" }
		),
		@ApiGlobalSection(
			title = "Status codes",
			paragraphs = { "/jsondocfile:/jsondoc/global-responsestatuscodes.html" }
		)
	}
)
public class GlobalDocumentation {

}

To correctly let JSONDoc find the static files, they need to be on the classpath. For example, put them in the src/main/resources directory, and specify the relative path to that directory, like /jsondoc/filename.html. To make this work properly, these files must be prefixed with /jsondocfile:.

Annotation to document changelogs

It's useful to document changes occurred in the new version of your api. This can be done easily with this annotation:

package org.jsondoc.sample.global;

import org.jsondoc.core.annotation.global.ApiChangelog;
import org.jsondoc.core.annotation.global.ApiChangelogSet;

@ApiChangelogSet(
	changlogs = {
		@ApiChangelog(changes = { "Changelog #5", "Changelog #6" }, version = "2.0"),
		@ApiChangelog(changes = { "Changelog #2", "Changelog #3", "Changelog #4" }, version = "1.1"),
		@ApiChangelog(changes = { "Changelog #1" }, version = "1.0")
	}
)		
public class ChangelogDocumentation {

}

Annotation to document migrations

It's useful to document steps that must be made by api users to migrate from one version to another one. This can be done easily with this annotation:

package org.jsondoc.sample.global;

import org.jsondoc.core.annotation.global.ApiMigration;
import org.jsondoc.core.annotation.global.ApiMigrationSet;

@ApiMigrationSet(
	migrations = { 
		@ApiMigration(fromversion = "1.1", steps = { "Step #3" }, toversion = "2.0"),
		@ApiMigration(fromversion = "1.0", steps = { "Step #1", "Step #2" }, toversion = "1.1")
	}
)
public class MigrationDocumentation {

}

Version 1.2.17 | Licensed under MIT License

GitHub Project | Issues