We live in a world that is powered by APIs. OpenAPI is a specification and set of related tooling that can make it easy to design, describe, and help build an API in many different languages. See how easy it is to hit the ground running using OpenAPI, Spotlight, and OpenAPI Generator to drop in an API into any project.

1. @dragonmantank
Dead Simple APIs with OpenAPI

2. @dragonmantank
What is OpenAPI?

3. @dragonmantank
● Information about the
API
● Define endpoints that
are available
● What requests look
like
● What responses look
like
● Authentication
Methods
http://spec.openapis.org/oas/v3.0.3

4. @dragonmantank
(It's a specification)
● Information about the
API
● Define endpoints that
are available
● What requests look
like
● What responses look
like
● Authentication
Methods
http://spec.openapis.org/oas/v3.0.3

5. @dragonmantank
Why OpenAPI?

6. @dragonmantank
Documentation Generation

7. @dragonmantank
Description as Code

8. @dragonmantank

9. @dragonmantank
Tooling Integrations
https://openapi.tools/

10. @dragonmantank https://github.com/Nexmo/nexmo-oas-renderer

11. @dragonmantank
Designing APIs

12. @dragonmantank
(It's a specification)
● Information about the
API
● Define endpoints that
are available
● What requests look
like
● What responses look
like
● Authentication
Methods
http://spec.openapis.org/oas/v3.0.312

13. @dragonmantank
(It's a specification)
● Information about
the API
● Define endpoints that
are available
● What requests look
like
● What responses look
like
● Authentication
Methods
http://spec.openapis.org/oas/v3.0.313

14. @dragonmantank
openapi: 3.0.0
info:
version: 1.2.5
title: Voice API
description: "The Voice API [...]"
contact:
name: Nexmo DevRel
email: devrel@nexmo.com
url: "https://developer.nexmo.com"
servers:
- url: https://api.nexmo.com/v1/calls
Information Header
http://spec.openapis.org/oas/v3.0.3#openapi-object

15. @dragonmantank
openapi: 3.0.0
info:
version: 1.2.5
title: Voice API
description: "The Voice API [...]"
contact:
name: Nexmo DevRel
email: devrel@nexmo.com
url:
"https://developer.nexmo.com"
servers:
- url: https://api.nexmo.com/v1/calls
Information Header
http://spec.openapis.org/oas/v3.0.3#openapi-object

16. @dragonmantank
openapi: 3.0.0
info:
version: 1.2.5
title: Voice API
description: "The Voice API [...]"
contact:
name: Nexmo DevRel
email: devrel@nexmo.com
url: "https://developer.nexmo.com"
servers:
- url: https://api.nexmo.com/v1/calls
Information Header
http://spec.openapis.org/oas/v3.0.3#openapi-object

17. @dragonmantank
openapi: 3.0.0
info:
version: 1.2.5
title: Voice API
description: "The Voice API [...]"
contact:
name: Nexmo DevRel
email: devrel@nexmo.com
url:
"https://developer.nexmo.com"
servers:
- url: https://api.nexmo.com/v1/calls
Information Header
http://spec.openapis.org/oas/v3.0.3#openapi-object

18. @dragonmantank
(It's a specification)
● Information about the
API
● Define endpoints
that are available
● What requests look
like
● What responses look
like
● Authentication
Methods
http://spec.openapis.org/oas/v3.0.318

19. @dragonmantank
[Information Header]
paths:
"/":
"/{uuid}":
"/{uuid}/stream":
"/{uuid}/talk":
"/{uuid}/dtmf":
Path Information
http://spec.openapis.org/oas/v3.0.3#paths-object

20. @dragonmantank
(It's a specification)
● Information about the
API
● Define endpoints that
are available
● What requests look
like
● What responses look
like
● Authentication
Methods
http://spec.openapis.org/oas/v3.0.320

21. @dragonmantank
[Information Header]
paths:
"/":
post:
get:
[...]
Request Structure
http://spec.openapis.org/oas/v3.0.3#path-item-object

22. @dragonmantank
[Information Header]
paths:
"/":
get:
summary: Get details of your calls
description: Get details [...]
operationId: getCalls
parameters:
- name: status
in: query
description: Filter calls [...]
schema:
type: string
example: started
post:
[...]
[...]
Request Structure
http://spec.openapis.org/oas/v3.0.3#operation-object

23. @dragonmantank
(It's a specification)
● Information about the
API
● Define endpoints that
are available
● What requests look
like
● What responses look
like
● Authentication
Methods
http://spec.openapis.org/oas/v3.0.323

24. @dragonmantank
[Information Header]
paths:
"/":
get:
[...]
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
count:
type: integer
post:
[...]
[...]
Response Structure
http://spec.openapis.org/oas/v3.0.3#response-object

25. @dragonmantank
[Information Header]
paths:
"/":
get:
[...]
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
count:
type: integer
post:
[...]
[...]
Response Structure
http://spec.openapis.org/oas/v3.0.3#response-object

26. @dragonmantank
[Information Header]
paths:
"/":
get:
[...]
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
count:
type: integer
post:
[...]
[...]
Response Structure
http://spec.openapis.org/oas/v3.0.3#response-object

27. @dragonmantank
responses:
'200':
$ref: '#/components/responses/ConversationLite'
Response Structure
http://spec.openapis.org/oas/v3.0.3#reference-object

28. @dragonmantank
[Information Header]
[Path Information]
components:
responses:
ConversationLite:
content:
application/json:
schema:
type: object
properties:
id:
$ref: '#/components/[...]'
href:
$ref: '#/components/[...]'
Response Structure
http://spec.openapis.org/oas/v3.0.3#reference-object

29. @dragonmantank
(It's a specification)
● Information about the
API
● Define endpoints that
are available
● What requests look
like
● What responses look
like
● Authentication
Methods
http://spec.openapis.org/oas/v3.0.329

30. @dragonmantank
[Information Header]
paths:
"/":
get:
security:
- bearerAuth: []
summary: Get details of your calls
description: Get details [...]
operationId: getCalls
parameters:
- name: status
in: query
description: Filter calls [...]
schema:
type: string
example: started
post:
[...]
[...]
Request Structure
http://spec.openapis.org/oas/v3.0.3#security-scheme-object

31. @dragonmantank
[Information Header]
paths:
"/":
get:
security:
- bearerAuth: []
summary: Get details of your
calls
description: Get details [...]
operationId: getCalls
parameters:
- name: status
in: query
description: Filter calls [...]
schema:
type: string
example: started
post:
[...]
[...]
Request Structure
http://spec.openapis.org/oas/v3.0.3#security-scheme-object

32. @dragonmantank https://stoplight.io/studio/

33. @dragonmantank https://stoplight.io/studio/

34. @dragonmantank

35. @dragonmantank

36. @dragonmantank

37. @dragonmantank

38. @dragonmantank

39. @dragonmantank
Prototyping and Mocking APIs

40. @dragonmantank https://stoplight.io/open-source/prism/

41. @dragonmantank https://stoplight.io/open-source/prism/

42. @dragonmantank

43. @dragonmantank

44. @dragonmantank

45. @dragonmantank

46. @dragonmantank https://www.postman.com/

47. @dragonmantank https://www.postman.com/collection

48. @dragonmantank
Generating API Code
https://github.com/OpenAPITools/openapi-generator

49. @dragonmantank
● ASP.Net
● C++
● Golang
● Java
● PHP
● NodeJS Express
● Ruby on Rails
https://openapi-generator.tech/docs/generators

50. @dragonmantank
$ openapi-generator-cli
generate
-i Voice.v1.yaml
-g php-slim4
-o $(pwd)/server

51. @dragonmantank

52. @dragonmantank
$ openapi-generator-cli
generate
-i Voice.v1.yaml
-g php-laravel
-o $(pwd)/server

53. @dragonmantank

54. @dragonmantank

55. @dragonmantank
● ASP.Net
● C++
● Golang
● Java
● PHP
● NodeJS
● Ruby
https://openapi-generator.tech/docs/generators

56. @dragonmantank
$ openapi-generator-cli
generate
-i Voice.v1.yaml
-g php
-o $(pwd)/sdk

57. @dragonmantank

58. @dragonmantank

59. @dragonmantank
● Document your
API
● Test your API
● Fast-track your
development
59

60. @dragonmantank
● Document your
API
● Test your API
● Fast-track your
development
60

61. @dragonmantank
● Document your
API
● Test your API
● Fast-track your
development
61

62. @dragonmantank
● Document your
API
● Test your API
● Fast-track your
development
62

63. @dragonmantank
Chris Tankersley
Developer Advocate at
Nexmo/Vonage
@dragonmantank
chris@ctankersley.com