http://idratherbewriting.com/learnapidoc/
Tools (implements 3.0): https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md
Converter, from 2.0->3.0: https://openapi-converter.herokuapp.com/
RESTful API & Documentation - over http, language agnostic, a style not a standard, light weight, resource (represented by URL) focused, methods: GET(read) POST (create), PUT (update), and DELETE (remove). REST APIs are stateless and cacheable. Other feature include "links in the responses to allow users to page through to additional items. This feature is called HATEOAS, or Hypermedia As The Engine of Application State." Now, without a doubt the OpenAPI specification is the most popular for documenting REST API. However these REST API specifications mostly describe the reference endpoints in an API. While the reference topics are important, you will likely have a lot more documentation to write.
" https://diigo.com/0cn57a
The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services. Although it's recommended, it only cover reference documentation. It doesn't provide tutor (getting started), information about getting API key, how to run a sample, rate limits and many other details. It cannot replace user guide. Also does not handle complex inter dependencies or setup workflows etc.
Swagger is the most widely used tooling ecosystem for developing APIs with the OpenAPI Specification (OAS).
Swagger Editor: create OAS definition
Swagger Codegen to generate server implementation.
Swagger UI to visualize and document your OAS definition, with ability to actually test out the API (call it) - however don't do it to a production API
Design, document and develop APIs as a team using SwaggerHub
OpenAPI uses JSON or YAML(converts to JSON). There are 8 objects at the root level in the OpenAPI 3.0 spec.
openapi : openapi: "3.0.1"
info: information, many properties optional; in any description MarkDown can be used.
servers - supply base bath; apply to each operation obj unless overridden ("servers" under a path)
url: the base path including protocol, host and path (recommend version in path); can specify multiple each with description (prod, beta, etc.) and user can select the environment from a drop down. Can use variables in url to be populated in runtime.
paths - the real stuff here
start by listing paths (resources) and operations (GET/POST/PUT/DELETE)
operation objects - see below
see parameters & responses objects below
components - define re-usable definitions that might appear in multiple places (parameters, responses), for reuse or tidiness; can be stored in a separate file; use $ref to refer ($ref: "folder/person.yaml#/Person" refer a different file in sub-folder)
security(array) - apply to each operation obj unless overridden; array of security requirement object which is {declared_security_scheme_name: [list of scope names in "oath2" or "openIdConnect" type scheme, otherwise empty]} ; see securitySchemes in components.
tags - way to group paths in UI display, list of tags object which is {name: a name, description: optional description as subtitle}
externalDocs: {description: some description, url: https://a.url/}
tags: to organize DISPLAY of the path under headings, a list
summary: A brief overview (5-10 words)
description: full description, MarkDown allowed
externalDocs (object): Links to external documentation
operationId: A unique (among all operations in the API) identifier for the operation (may be used for tools to generate method so follow common programming conventions)
parameters (object): "name"+"in"(path/query/header/cookie) parameters. Can refer to a component object. See below.
requestBody (object): The request body. Can refer to a component object. See below.
responses (object): Response. Usually just refer to a component object. Responses use standard status codes.
callbacks (object): call back initiated by server if desired. Can refer to a component object.
deprecated: Boolean, commonly omitted
security (object): Security authorization method. Only when overriding root level.
servers (object): Only when overriding root level.
name:
in: header, path, query, or cookie
description:
required: boolean
deprecated: boolean
allowEmptyValue: boolean
style: how parameter data is serialized (converted to bytes during data transfer).
explode: advanced parameter related to arrays.
allowReserved: whether reserved characters are allowed.
schema (object): The schema or model, can also contain an example object.
example: An example.
examples (object): An example including the schema, appear in Swagger UI.
For reuse or tidiness, to be referred elsewhere. To reference, use "$ref: '#/components/[parameters etc.]/[something]'"
Can contain:
schemas - JSON schema specification Wight Draft 00; note there's an example property - Swagger UI will use it to automatically build a full code example in the Response section; CHEAT: use Stoplight or other tools to generate JSON schema
responses - usually with reference to a schema, and Swagger UI would piece together the examples into a sample response
parameters
examples
requestBody
headers
securitySchemes
links
callbacks
type: "apiKey", "http", "oauth2", "openIdConnect".
description
name (apiKey only & required): name of the header, query or cookie parameter to be used
in (apiKey only & required): location of the API key, "query", "header" or "cookie".
scheme (http type only & required): name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.
bearerFormat (http only):
flows (OAuth): Flows Object, OAuth2 configuration
openIdConnectUrl (openIdConnect only): a URL.
(1) Code first, automatically generating the specification document
Tools available to generate specification document through annotations. Swagger for instance has libraries as part of Swagger Codegen project. See reference for more. Benefit: allow developers to easily write documentation within their IDE, make sure new features are always documented, and keep the documentation more current. Somewhat like JavaDoc. Con: Someone has to know exactly what annotations to add and how to add them. Also, see discussion below.
(2) Spec-first development
Michael Stowe recommends that teams implement the specification by hand and then treat the specification document as a contract that developers use when doing the actual coding. Developers consult the specification document to see what the parameter names should be called, what the responses should be, and so on. Since versioning APIs is extremely difficult (you have to support each new version going forward with full backwards compatibility to previous versions), you want to avoid the “fail fast” approach that is so commonly celebrated with agile. Documentation versioning also becomes a nightmare. Also SmartBear say it’s now more common for teams to manually write the spec rather than embed source annotations in programming code to auto-generate the spec. Also defining the spec before coding also helps teams produce better APIs.
OpenAPI Map - visual map to find what's in the specification: https://openapi-map.apihandyman.io/