Introduction to OpenAPI Specification

Leveraging API Specification Languages Lorna Mitchell, Nexmo

Describing APIs • Describe RESTful HTTP APIs in a machine-readable way Then the machine can read it and write: • API reference documentation • Code SDKs • Postman collections • Mock servers @lornajane

API Spec Languages • OpenAPI is an open standard, and is used in this talk • RAML from Mulesoft (who also now support OpenAPI) • API Blueprint from Apiary @lornajane

Spec-First API Design @lornajane

New APIs or Existing Ones? @lornajane

New APIs or Existing Ones? Yes! @lornajane

Anatomy of OpenAPI Spec @lornajane

Anatomy of OpenAPI Spec Top-level elements: • openapi • info • servers • paths • components • security • tags @lornajane

OpenAPI Spec Examples A JSON or YAML file holds the description (this is YAML) openapi: 3.0.0 servers: - url: ‘https://api.nexmo.com/ni’ info: title: Number Insight API version: 1.0.3 description: >Nexmo’s Number Insight API delivers real-time intelligence about the validity … a few hundred more lines here @lornajane

Documenting an Endpoint paths: ‘/basic/{format}’: parameters: - $ref: ‘#/components/parameters/format’ get: operationId: getNumberInsightBasic parameters: - $ref: ‘#/components/parameters/number’ - $ref: ‘#/components/parameters/country’ responses: ‘200’: description: OK content: application/json: schema: $ref: ‘#/components/schemas/niResponseJsonBasic’ @lornajane

Reference Parameters components: parameters: number: name: number in: query description: ‘A single phone number that you need insight about in national example: ‘447700900000’ required: true country: name: country in: query example: ‘GB’ description: ‘If a number does not have a country code or is uncertain, set schema: type: string pattern: ‘[A-Z]{2}’ @lornajane

That looks complicated! @lornajane

Editing Tools There are editors with helpful tools • Stoplight is highly recommended if you like a web interface https://stoplight.io • I like Atom with linter-swagger https://atom.io • Try SwaggerUI, SwaggerHub, etc https://swagger.io/tools/ • APICurio Studio gets good reviews https://www.apicur.io/ @lornajane

Please use Source Control See also: https://gitworkbook.com @lornajane

Validation Tools Tools that check or “lint” your file. • Speccy is a CLI tool with configurable rules http://speccy.io/ • Spectral is a newer CLI tool, also with rules https://github.com/stoplightio/spectral • Open API Spec Validator https://github.com/p1c2u/openapi-spec-validator @lornajane

Preview Tools OAS is a standard! So any preview should do: • ReDoc is great https://github.com/Rebilly/ReDoc • You can run OpenApi-GUI locally https://github.com/mermade/openapi-gui • Nexmo uses a custom renderer https://developer.nexmo.com/api • Stoplight shows documentation as you go (more on this later) https://stoplight.io @lornajane

Docs Example: ReDoc @lornajane

Docs Example: Nexmo @lornajane

Docs Example: Stoplight @lornajane

Stoplight Online Editor @lornajane

Stoplight Design View @lornajane

Imported into Postman @lornajane

Generated Code Libraries This example is from OpenAPI Generator https://github.com/OpenAPITools/openapi-generator docker run —rm -v ${PWD}:/local \ openapitools/openapi-generator-cli generate -i number-insight.yml -g php -o /local/out/php @lornajane

Generated Code Libraries To use it: 1 2 3 4 5 6 7 8 9 10 11 12 13 require_once(‘out/php/vendor/autoload.php’); // copy code from README, set API key and secret $apiInstance = new OpenAPI\Client\Api\DefaultApi( new GuzzleHttp\Client(), $config); $format = “json”; $number = “447700900000”; try { $result = $apiInstance->getNumberInsightBasic($format, $number); print_r($result); } catch (Exception $e) { echo ‘Exception when calling DefaultApi->getNumberInsightBasic’; } @lornajane

Creating OpenAPI Specs is like eating an elephant @lornajane

Uses for OpenAPI Spec @lornajane

Resources • https://www.openapis.org • https://openapi.tools • https://apievangelist.com • https://stoplight.io • https://speccy.io • https://github.com/Rebilly/ReDoc • https://github.com/openapitools/openapi-generator @lornajane