apidoc spec 0.11.80

Specification of apidoc api.json schema

Resources

No resources

Headers

No headers

Imports

No imports

Enums

method

GET
POST
PUT
PATCH
DELETE
HEAD
CONNECT
OPTIONS
TRACE

parameter_location

Path
Query
Form
Header

response_code_option

Default

Models

apidoc

Example Json: Minimal | Full
Field Type Required? Default Description
version string Yes -

Example: 1.0.3

application

Example Json: Minimal | Full
Field Type Required? Default Description
key string Yes -

Unique key identifying this application

attribute

Example Json: Minimal | Full

Represents an additional attribute that is attached to one of the objects in apidoc. The main use case is to capture additional metadata that doesn’t necessarily define the API but aids in code generation. Examples would be hints for certain code generators about classes to extend, interfaces to implement, annotations to add, names to assign to certain methods, etc. The specific attributes will be applicable only in the context of the specific code generators usings them.

Field Type Required? Default Description
name string Yes -

value object Yes -

description string No -

deprecation deprecation No -

body

Example Json: Minimal | Full
Field Type Required? Default Description
type string Yes -

description string No -

deprecation deprecation No -

attributes [attribute] No []

contact

Example Json: Minimal | Full

Describes the primary contact for this service

Field Type Required? Default Description
name string No -

Example: Michael Bryzek

url string No -

Example: http://www.apidoc.me

email string No -

Example: michael@test.apidoc.me

deprecation

Example Json: Minimal | Full

Indicates that this particular element is considered deprecated in the API. See the description for details

Field Type Required? Default Description
description string No -

enum

Example Json: Minimal | Full
Field Type Required? Default Description
name string Yes -

plural string Yes -

description string No -

deprecation deprecation No -

values [enum_value] Yes -

attributes [attribute] No []

enum_value

Example Json: Minimal | Full
Field Type Required? Default Description
name string Yes -

description string No -

deprecation deprecation No -

attributes [attribute] No []

field

Example Json: Minimal | Full
Field Type Required? Default Description
name string Yes -

type string Yes -

description string No -

deprecation deprecation No -

default string No -

required boolean Yes -

minimum long No -

maximum long No -

example string No -

attributes [attribute] No []

header

Example Json: Minimal | Full
Field Type Required? Default Description
name string Yes -

type string Yes -

description string No -

deprecation deprecation No -

required boolean Yes -

default string No -

attributes [attribute] No []

import

Example Json: Minimal | Full

An import is used to declare a dependency on another application. This allows you to reference the models and or enums from that application in your own app.

Field Type Required? Default Description
uri string Yes -

Full URI to the service.json file of the service we are importing

Example: http://www.apidoc.me/bryzek/apidoc-spec/0.7.38/service.json

namespace string Yes -

the fully qualified namespace that we have imported

Example: com.bryzek.apidoc

organization organization Yes -

application application Yes -

version string Yes -

The version of the service that we are importing

Example: 1.0.0

enums [string] No []

Models made available by this import

unions [string] No []

Unions made available by this import

models [string] No []

Models made available by this import

info

Example Json: Minimal | Full

General metadata about this service

Field Type Required? Default Description
license license No -

contact contact No -

license

Example Json: Minimal | Full

Describes the software license contact for this service

Field Type Required? Default Description
name string Yes -

Example: MIT

url string No -

Example: http://opensource.org/licenses/MIT

model

Example Json: Minimal | Full
Field Type Required? Default Description
name string Yes -

plural string Yes -

description string No -

deprecation deprecation No -

fields [field] Yes -

attributes [attribute] No []

operation

Example Json: Minimal | Full
Field Type Required? Default Description
method method Yes -

path string Yes -

The full path to this operation, relative to the service’s base url.

description string No -

deprecation deprecation No -

body body No -

parameters [parameter] No []

responses [response] No []

attributes [attribute] No []

organization

Example Json: Minimal | Full
Field Type Required? Default Description
key string Yes -

Unique key identifying the organization that owns this service

parameter

Example Json: Minimal | Full
Field Type Required? Default Description
name string Yes -

type string Yes -

location parameter_location Yes -

description string No -

deprecation deprecation No -

required boolean Yes -

default string No -

minimum long No -

maximum long No -

example string No -

resource

Example Json: Minimal | Full
Field Type Required? Default Description
type string Yes -

The type of this resource will map to a defined model, enum, or union type

plural string Yes -

path string No -

The path to this specific resource. This was added in 2016 to help us differentiate between the resource path and the operation path which can be helpful when, for example, generating method names for operations. This field is optional as some of our input formats (e.g. swagger) do not explicitly differentiate resoure paths.

description string No -

deprecation deprecation No -

operations [operation] Yes -

attributes [attribute] No []

response

Example Json: Minimal | Full
Field Type Required? Default Description
code response_code Yes -

type string Yes -

headers [header] No -

description string No -

deprecation deprecation No -

service

Example Json: Minimal | Full
Field Type Required? Default Description
apidoc apidoc Yes -

Documents that this is an apidoc document, noting the specific version used. Internally the version is then used for backwards compatibility when applicable as new features are added to apidoc.

name string Yes -

organization organization Yes -

application application Yes -

namespace string Yes -

Fully qualified namespace for this service

Example: com.bryzek.apidoc

version string Yes -

Example: 1.0.0

base_url string No -

description string No -

info info Yes -

headers [header] No []

imports [import] No []

enums [enum] No []

unions [union] No []

models [model] No []

resources [resource] No []

attributes [attribute] No []

union

Example Json: Minimal | Full
Field Type Required? Default Description
name string Yes -

plural string Yes -

discriminator string No -

If a type discriminator is provided, serialization of these union types will always contain a field named with the value of the discriminator that will contain the name of the type. This provides a simpler (for many use cases) JSON serialization/deserialization mechanism. When specified, apidoc itself will verify that none of the types in the union type itself contain a field with the same name as the discriminator

Example: discriminator or type

description string No -

deprecation deprecation No -

types [union_type] Yes -

The names of the types that make up this union type

Minimum: 1

attributes [attribute] No []

union_type

Example Json: Minimal | Full

Metadata about one of the types that is part of a union type

Field Type Required? Default Description
type string Yes -

The name of a type (a primitive, model name, or enum name) that makes up this union type

description string No -

deprecation deprecation No -

attributes [attribute] No []

Unions

response_code

Example Json: Minimal | Full
  • Type discriminator: N/A
integer

Documents an HTTP status code (e.g. 200, 409, etc.)

response_code_option

An individual operation can specify a response code of default to handle all other response codes. This is most useful for providing consistent error handling from an operation.