Nuts Open API

NOAPI is a simple yet powerful commandline tool for generating professional OpenApi Pdf file based on OpenApi 3.0 Format.

Supported features are

• OpenAPI 3.0 compatible
• Supported Yaml, JSON and TSON formats (TSON support is described below; JSON and TSON are fully round-trippable, YAML is best-effort — see docs/yaml-limitations.md)
• Supports custom text
• Supports conditional generation
• Supports change list generation
• Marks deprecated operations, parameters, headers, schemas and properties (deprecated in JSON/YAML, @deprecated in TSON) and shows them explicitly in the generated document and PDF
• Lists every schema type under SCHEMA TYPES, including object, enum, primitive, array and reference schemas
• Conversion between JSON / YAML / TSON (noapi convert)

Input formats

An API document or a NoAPI configuration document is detected from its extension first (.json, .yaml / .yml, .tson), then from a content sniff. An explicit --from / --json / --yaml / --tson override always wins.

• JSON — read with the lenient Nuts JSON reader (comments and trailing commas allowed).
• YAML — read with the Nuts YAML reader (best effort; see the limitations document).
• TSON — read with the Nuts TSON reader, then passed through the condensed desugarer. Both the condensed dialect and plain TSON (including this repo's historical plain-TSON output) are accepted.

The condensed TSON dialect is fully documented in docs/condensed-tson.md.

Converting documents

noapi convert <input> [<input> ...] [-o <output>] \
      [--from auto|json|yaml|tson] [--to auto|json|yaml|tson] \
      [--kind auto|api|config] [--style condensed|plain] [--force] [--strict]

• --to defaults to the output file extension, otherwise to tson.
• -o defaults to the input name with the target extension.
• --style condensed (default) emits condensed TSON; plain emits plain TSON.
• --kind selects API vs configuration document; auto detects it.
• --force is required to overwrite an existing output file.
• --strict turns example/schema validation mismatches into fatal errors (see below).

Examples:

# JSON API document -> condensed TSON
noapi convert api.json -o api.tson

# condensed TSON -> JSON (format inferred from the .json extension)
noapi convert api.tson -o api.json

# API -> YAML (best effort)
noapi convert api.json --to yaml -o api.yaml

# configuration document
noapi convert config.json --kind config -o config.tson

noapi convert (the command word) and --convert are equivalent. The global --json / --yaml / --tson flags select the target format as well.

Example / schema checking

Every example of an API document is checked against the constraints of the schema it documents (E_EXAMPLE_MISMATCH). By default a mismatch is only printed as a warning on the standard error and the run continues. With --strict (accepted by convert and by the pdf generation) the first mismatching document aborts the run.

Deprecated operations, parameters, headers, schemas and properties

deprecated is the OpenAPI 3.0 flag. NoAPI reads it in all supported formats:

• JSON / YAML — the plain deprecated: true (or false) pair, on Operation, Parameter, Header and Schema Objects.
• TSON — either the plain pair or the @deprecated annotation. The annotation is accepted on an operation head, on a path item, on a parameter, on a header, on a schema declaration and on a property. @deprecated(false) writes an explicit false and the condensed writer keeps that explicit value.

NoAPI also accepts deprecated on a path item and pushes it down into each operation (canonicalization C3), so the whole path can be retired at once.

In the generated document and PDF the flag is shown explicitly as [DEPRECATED] next to the operation title, parameter name, header name, schema type title and field name. The examples/deprecated folder contains the same API in JSON, YAML and TSON.

Enabled operations and schema types

Operations with enabled: false (or enabled evaluating to false) are omitted from the generated document. The SCHEMA TYPES section follows the same rule:

• a schema referenced by at least one enabled operation is shown;
• a schema referenced only by disabled operations is hidden;
• a schema referenced by another shown schema is kept visible (transitively);
• a schema that is not referenced by any path is still shown, because it is not tied to a disabled path;
• the “This type is used in” list only mentions enabled operations, even when the same schema is also used by a disabled operation on the same path or on another path.

Self-verification

The condensed writer never emits unverified text. After writing condensed TSON, NoAPI re-reads it with the real parser, desugars it, canonicalizes both trees and diffs them. On any mismatch (or writer error) it falls back to plain TSON, which is lossless. The convert command prints a note when this happens.

Canonicalization

Round trips are identical except for the following canonicalizations (applied to both sides before comparison):

• C1 empty tags, parameters, required arrays and empty components.responses / components.parameters objects are dropped.
• C2 required is re-ordered to property order; names not in properties are kept.
• C3 path-level summary, description, parameters, enabled, deprecated are pushed into each operation.
• C4 parameter-level schema keywords (type, format, …) move into schema.
• C5 format: "object::X" ↔ bare X only on object.
• C6 multi-line strings are compared after trimming trailing whitespace on each line.
• C7 integer-looking response keys become strings.
• C8 the document id is stored in custom.openapi-document-id.
• C9 the members of an apiKey security scheme are ordered type, name, in.
• C10 a schema's deprecated member is placed last, matching the order produced when the condensed @deprecated annotation is read back.
• C11 an enum schema is ordered type, enum, then its other members, matching the condensed enum(values: […]) sugar.

Everything else must be identical, including key order and array order.