Introduction to OpenAPI Specification

Introduction to Open API Specification Lorna Mitchell, Nexmo

Describing APIs • Describe RESTful HTTP APIs in a machine-readable way • API description is independent of outputs such as documentation • Enable things that are not “just” documentation @lornajane

Spec-First API Design @lornajane

About OpenAPI Spec API description language formerly known as “Swagger”. Became “OpenAPI Spec” -> v3 released (some tools are still catching up on v3) @lornajane

New APIs or Existing Ones? @lornajane

New APIs or Existing Ones? Yes! @lornajane

Who Writes OpenAPI Specs? @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.1.0 description: >Nexmo’s Number Insight API delivers real-time intelligence about the vali … 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

Example Parameter number: name: number in: query description: ‘A single phone number that you need insight about in national or example: ‘447700900000’ required: true schema: type: string pattern: ‘^[0-9-+()\s]*$’ @lornajane

Example Response niResponseJsonBasic: type: object properties: status: $ref: ‘#/components/schemas/niBasicStatus’ status_message: type: string description: ‘The status description of your request.’ example: ‘Success’ request_id: type: string description: ‘The unique identifier for your request. This is a alphanumeri example: ‘aaaaaaaa-bbbb-cccc-dddd-0123456789ab’ maxLength: 40 … @lornajane

That looks complicated! @lornajane

Rendered Example: ReDoc @lornajane

Rendered Example: Nexmo @lornajane

Imported into Postman @lornajane

Tools To Get Things Done @lornajane

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

Editing Tools There are editors with helpful tools • 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/ • Stoplight looks interesting https://stoplight.io (feel free to tweet your best tools at me, I’ll share them all later) @lornajane

OAS in Atom @lornajane

Validation Tools Tools that check or “lint” your file. • Speccy is a CLI tool with configurable rules http://speccy.io/ • Open API Spec Validator https://github.com/p1c2u/openapi-spec-validator Set up in your editor or use a watch command, e.g.: watch -n 1 speccy lint myspec.yml @lornajane

Preview Tools OAS is a standard! So any preview should do: • ReDoc is great https://github.com/Rebilly/ReDoc • Speccy also wraps ReDoc for its serve command • You can run OpenApi-GUI locally https://github.com/mermade/openapi-gui @lornajane

Creating OpenAPI Specs is like eating an elephant @lornajane

Uses for OpenAPI Spec @lornajane

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

@lornajane

Bonus Extra Slides @lornajane

Code Generators Libraries can be generated as easily as docs. For PHP (and so many other languages) try https://github.com/openapitools/openapi-generator Pull docker image, generate PHP code from your OpenAPI Spec @lornajane

Code Generator Example 1 2 3 4 5 6 7 8 9 10 11 12 13 $config->setUsername(NEXMO_API_KEY); $config->setPassword(NEXMO_API_SECRET); $client = new OpenAPI\Client\Api\DefaultApi( new GuzzleHttp\Client(), $config); $obj = new \OpenAPI\Client\Model\InlineObject(); try { $result = $client->retrieveSecrets(NEXMO_API_KEY, $obj); print_r($result); } catch (Exception $e) { echo ‘Exception when calling DefaultApi->retrieveSecrets: ‘, $e->getMessag } @lornajane

Code Generator Example 1 2 3 4 5 6 7 8 9 10 11 12 13 $config->setUsername(NEXMO_API_KEY); $config->setPassword(NEXMO_API_SECRET); $client = new OpenAPI\Client\Api\DefaultApi( new GuzzleHttp\Client(), $config); $obj = new \OpenAPI\Client\Model\InlineObject(); try { $result = $client->retrieveSecrets(NEXMO_API_KEY, $obj); print_r($result); } catch (Exception $e) { echo ‘Exception when calling DefaultApi->retrieveSecrets: ‘, $e->getMessag } @lornajane