OpenAPI & Modeling

OpenAPI is a specification language

OpenAPI is a specification language for REST APIs that allows to communicate:

technical specifications
metadata
docs & references

OpenAPI is driven by a Foundation

The OpenAPI Foundation is an initiative under the Linux Foundation, participated by government & companies (gov.uk, Microsoft, Google, Oracle, IBM, ..):

Driver for API adoption
Evolution of Swagger 2.0
Lightweight format: YAML
Generates docs & code via tools (swagger-editor, apicur.io)
Allows reusable components via hyperlink (eg. $ref)

OpenAPI is WSDL for REST APIs

OpenAPI Editor

Every OAS3 document begins with

openapi: 3.0.0

Run next cell if it's blank ;)



In [ ]:

    
remote_yaml = 'https://raw.githubusercontent.com/teamdigitale/api-starter-kit/master/openapi/simple.yaml.src'
render_markdown(f'''

[Swagger Editor]({oas_editor_url(remote_yaml)}) is a simple webapp
for editing OpenAPI 3 language specs.


''')

Start with Metadata

In OAS3 we should first describe api metadata, to clarify:

API goals, audience and context;
Terms of service;
Versioning.

Here's a simple OAS3 metadata part, contained in the info section.

openapi: 3.0.0
info:
  version: "1.0.0"
  title: |-
    Write a short, clear name of your service.
  description: |
    This field may contain the markdown documentation of the api,
    including references to other docs and examples.

  # Legal references and terms of services.
  termsOfService: 'http://swagger.io/terms/'
  contact:
    email: robipolli@gmail.com
    name: Roberto Polli
    url: https://twitter.com/ioggstream
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

OpenAPI Metadata exercise



In [ ]:

    
render_markdown(f'''

1- open [this incomplete OAS3 spec](/edit/notebooks/oas3/ex-01-info.yaml).

2- copy its content in the [Swagger Editor Online]({oas_editor_url('')}) fixing all errors 
   and adding the missing informations.

3- describe the first API we're going to implement: a service which returns the current
   timestamp in [RFC5454](https://tools.ietf.org/html/rfc5424#section-6.2.3) 
   UTC (eg. `2019-01-01T00:00:00Z`).
    
4- provide contact informations and terms of services. 

5- Feel free to add as many details as you want.

''')



In [ ]:

    
### Basic fields
### Terms of Services

Custom fields

In Italy we're experimenting with some custom fields to help catalogs and metadata

x-summary is an one-liner description for catalog purposes. The new OAS 3.1 standardizes it as summary

x-lifecycle can be used to communicate publishing and retiring informations

  x-lifecycle:
    published: 1970-01-01
    deprecated: 2050-01-01
    retired: 2050-06-01
    maturity: published

x-api-id you may want to assign a time-persistend UUID to your API, so that you can change its title

x-api-id: 00000000-0000-0000-0000-000000000000

x-gdpr with a list of roles

x-geodata add local references in a machine readable format

OpenAPI Metadata exercise: 2



In [ ]:

    
render_markdown(f'''

1- open [the previous OAS3 spec](/edit/notebooks/oas3/ex-01-info.yaml).

2- copy its content in the [Swagger Editor Online]({oas_editor_url('')}).

3- provide further informations via custom fields: if you think of any interesting 
   label, define them and comment properly using `#` 

''')

Go to the next lesson to learn connexion!



In [ ]: