A presentation at GOTO Copenhagen in in Copenhagen, Denmark by Lorna Jane Mitchell
Introduction to OpenAPI Lorna Mitchell, Nexmo
APIs are the engine of modern software development API descriptions power up our API workflows @lornajane
Spec-First API Design @lornajane
New APIs or Existing Ones? @lornajane
New APIs or Existing Ones? Yes! @lornajane
API Description Languages • API Blueprint from Apiary • RAML from Mulesoft (who also now support OpenAPI) • OpenAPI is an open standard, and is used in this talk • “The standard formerly known as Swagger” @lornajane
OpenAPI Descriptions WARNING may contain YAML @lornajane
MetaData openapi: 3.0.0 servers: - url: ‘https://api.nexmo.com/ni’ info: title: Number Insight API version: 1.0.4 description: Nexmo’s Number Insight API delivers real-time intelligence … contact: name: Nexmo DevRel email: devrel@nexmo.com url: ‘https://developer.nexmo.com/’ termsOfService: ‘https://www.nexmo.com/terms-of-use’ license: name: ‘The MIT License (MIT)’ url: ‘https://opensource.org/licenses/MIT’ @lornajane
Endpoints in OpenAPI Spec paths: ‘/basic/{format}’: get: operationId: getNumberInsightBasic ‘/standard/{format}’: get: operationId: getNumberInsightStandard ‘/advanced/async/{format}’: get: operationId: getNumberInsightAsync ‘/advanced/{format}’: get: operationId: getNumberInsightAdvanced @lornajane
Parameters and Responses parameters: - $ref: ‘#/components/parameters/format’ - $ref: ‘#/components/parameters/number’ - $ref: ‘#/components/parameters/country’ responses: ‘200’: description: OK content: application/json: schema: $ref: ‘#/components/schemas/niResponseJsonBasic’ text/xml: schema: $ref: ‘#/components/schemas/niResponseXmlBasic’ @lornajane
OpenAPI $ref Feature (Re)Use any block. For example the format parameter: components: parameters: format: name: format in: path required: true description: ‘The format of the response’ example: json schema: type: string enum: - ‘json’ - ‘xml’ @lornajane
That’s a lot of YAML … @lornajane
How to Edit OpenAPI Specs Option 1: your usual editor (this is https://atom.io) @lornajane
Text-Based API Descriptions @lornajane
How to Edit OpenAPI Specs Option 2: specialist tool https://stoplight.io/studio/ @lornajane
Validate and Check Style Spectral https://github.com/stoplightio/spectral Pick-and-mix the rules, and sprinkle in a few of your own! @lornajane
Even the machines can understand … now what? @lornajane
Generate Documentation Use your OpenAPI spec as the source for your API reference documentation • A choice of tools • Separate content and presentation • The spec supports and encourages examples @lornajane
Docs Example: ReDoc @lornajane
Docs Example: Nexmo @lornajane
Explore APIs with Postman @lornajane
OpenAPI Spec To Mock Server Prism is a mock server https://stoplight.io/prism/ @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
Finding Tools https://openapi.tools - a community listing @lornajane
OpenAPI: Brave New World @lornajane
Resources • https://developer.nexmo.com • https://openapis.org • https://stoplight.io (Studio, Prism and Spectral) • https://github.com/Nexmo/nexmo-oas-renderer • https://github.com/Redocly/redoc • https://openapi.tools @lornajane
@lornajane
Open API Specification is a machine and human readable way to describe APIs. From these specs we can generate documentation, create libraries, and ensure that our users know exactly what to expect from our APIs. This talk shows you around OAS from the beginning, showing how to create the specs and recommending some tools to help the process. Once you have the spec, things get interesting and this talk will showcase some of the things that you can offer once your API is described in this way. This session is recommended for writers looking to become more API-savvy and API engineers wanting to make their APIs more useful to their users.
