introduction to openapi · introduction to openapi lorna mitchell, nexmo. smile! developer...
TRANSCRIPT
![Page 1: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/1.jpg)
Introduction toOpenAPI
Lorna Mitchell, Nexmo
![Page 2: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/2.jpg)
APIs are the engine of modernsoftware development
API descriptions power up our APIworkflows
@lornajane
![Page 3: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/3.jpg)
Spec-First API Design
@lornajane
![Page 4: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/4.jpg)
New APIs or Existing Ones?
@lornajane
![Page 5: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/5.jpg)
New APIs or Existing Ones?
Yes!
@lornajane
![Page 6: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/6.jpg)
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
![Page 7: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/7.jpg)
OpenAPI Descriptions WARNING may contain YAML
@lornajane
![Page 8: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/8.jpg)
MetaDataopenapi: 3.0.0servers: - 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: [email protected] 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
![Page 9: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/9.jpg)
Endpoints in OpenAPI Specpaths: '/basic/{format}': get: operationId: getNumberInsightBasic
'/standard/{format}': get: operationId: getNumberInsightStandard
'/advanced/async/{format}': get: operationId: getNumberInsightAsync
'/advanced/{format}': get: operationId: getNumberInsightAdvanced
@lornajane
![Page 10: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/10.jpg)
Parameters and Responsesparameters: - $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
![Page 11: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/11.jpg)
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
![Page 12: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/12.jpg)
That's a lot of YAML ...
@lornajane
![Page 13: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/13.jpg)
How to Edit OpenAPI SpecsOption 1: your usual editor (this is https://atom.io)
@lornajane
![Page 14: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/14.jpg)
Text-Based API Descriptions
@lornajane
![Page 15: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/15.jpg)
How to Edit OpenAPI SpecsOption 2: specialist tool https://stoplight.io/studio/
@lornajane
![Page 16: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/16.jpg)
Validate and Check StyleSpectral https://github.com/stoplightio/spectral
Pick-and-mix the rules, and sprinkle in a few of your own!
@lornajane
![Page 17: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/17.jpg)
Even the machines can understand ...now what?
@lornajane
![Page 18: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/18.jpg)
Generate DocumentationUse your OpenAPI spec as the source for your API referencedocumentation • A choice of tools• Separate content and presentation• The spec supports and encourages examples
@lornajane
![Page 19: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/19.jpg)
Docs Example: ReDoc
@lornajane
![Page 20: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/20.jpg)
Docs Example: Nexmo
@lornajane
![Page 21: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/21.jpg)
Explore APIs with Postman
@lornajane
![Page 22: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/22.jpg)
OpenAPI Spec To Mock ServerPrism is a mock server https://stoplight.io/prism/
@lornajane
![Page 23: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/23.jpg)
Generated Code LibrariesThis example is from OpenAPI Generatorhttps://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
![Page 24: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/24.jpg)
Generated Code LibrariesTo use it: 1 require_once('out/php/vendor/autoload.php'); 2 // copy code from README, set API key and secret 3 4 $apiInstance = new OpenAPI\Client\Api\DefaultApi( 5 new GuzzleHttp\Client(), $config); 6 $format = "json"; 7 $number = "447700900000"; 8 try { 9 $result = $apiInstance->getNumberInsightBasic($format, $number);10 print_r($result);11 } catch (Exception $e) {12 echo 'Exception when calling DefaultApi->getNumberInsightBasic';13 }
@lornajane
![Page 25: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/25.jpg)
Finding Toolshttps://openapi.tools - a community listing
@lornajane
![Page 26: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/26.jpg)
OpenAPI: Brave New World
@lornajane
![Page 27: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/27.jpg)
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
![Page 28: Introduction to OpenAPI · Introduction to OpenAPI Lorna Mitchell, Nexmo. Smile! Developer Advocate, I LOVE APIs and docs. WHO HAS HEARD OF NEXMO?? OAS is about improving all aspects](https://reader030.vdocuments.us/reader030/viewer/2022040116/5ec9acbc5f0730394d28d1c1/html5/thumbnails/28.jpg)
@lornajane