Open API
satya - 8/7/2017, 7:01:51 PM
Introduction to Open API
Introduction to Open API
satya - 8/7/2017, 7:09:13 PM
Perhaps similar to WSDL for SOAP
The Initiative will extend the Swagger specification and format to create an open technical community within which members can easily contribute to building a vendor neutral, portable and open specification for providing metadata for RESTful APIs. This open specification will allow both humans and computers to discover and understand the capabilities of the respective services with a minimal amount of implementation logic. The Initiative will also promote and facilitate the adoption and use of an open API standard.
satya - 8/9/2017, 11:00:25 AM
Background
2015
Under Linux foundation
Based on Swagger 2.0
satya - 8/9/2017, 11:04:42 AM
Looks like a good starting point article
satya - 8/9/2017, 11:07:09 AM
OpenAPI specification describe the API
inputs
outputs
name
security
documentation
what ever else that may come
satya - 8/9/2017, 11:09:36 AM
You can write it in YAML or JSON, but YAML is preferred as it is readable
Credit: Taken from the URL above (YAML)
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
satya - 8/9/2017, 11:14:43 AM
Looks like there is a swagger editor to write the documentation
Looks like there is a swagger editor to write the documentation
Not sure why a dependency on node!
satya - 8/9/2017, 11:18:40 AM
What is the difference between Swagger and OpenAPI?
What is the difference between Swagger and OpenAPI?
Search for: What is the difference between Swagger and OpenAPI?
satya - 8/9/2017, 11:19:00 AM
Where does swagger end and OpenAPI begin?
Where does swagger end and OpenAPI begin?
satya - 8/9/2017, 11:19:24 AM
Mashery and OpenAPI
Mashery and OpenAPI
satya - 8/9/2017, 11:19:40 AM
What are good swagger API editors?
What are good swagger API editors?
satya - 8/9/2017, 11:21:52 AM
Critique of the OpenAPI and Swagger
Critique of the OpenAPI and Swagger
satya - 8/9/2017, 11:22:21 AM
How do you scale Swagger for lot of APIs or microservices?
How do you scale Swagger for lot of APIs or microservices?
Search for: How do you scale Swagger for lot of APIs or microservices?
satya - 8/9/2017, 11:23:16 AM
Why use another language like swagger when there is Javadoc?
Why use another language like swagger when there is Javadoc?
Search for: Why use another language like swagger when there is Javadoc?
satya - 8/9/2017, 11:38:10 AM
In a swagger file you can define types that can be referred to later: called definition
<Person>
<firstname/>
<lastname/>
<username/> //required
</person>
//Equivalent
definitions:
Person:
required:
username
properties:
firstname:
type:string
...etc
//Then you can use
items:
$ref: "#/definitions/Person"
satya - 8/9/2017, 11:43:26 AM
Here is an example of how a JSON Schema look like
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "integer"
},
"name": {
"description": "Name of the product",
"type": "string"
},
"price": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
},
"required": ["id", "name", "price"]
}
satya - 8/9/2017, 11:44:32 AM
Here is a github book on JSON Schema
satya - 8/9/2017, 11:59:43 AM
How is swagger used in API development
satya - 8/9/2017, 12:07:42 PM
What is swaggerhub?
What is swaggerhub?
satya - 8/9/2017, 12:11:14 PM
How is swagger used in API development?
How is swagger used in API development?
satya - 8/9/2017, 12:15:32 PM
An article on how to use swagger API
satya - 8/9/2017, 12:16:14 PM
Swagger tools
Swagger Editor
Swagger Codegen
Swagger UI
satya - 8/9/2017, 12:19:39 PM
Bottom up approach
//write
Develop the APIs in your language
//publish
Use tools to publish the swagger files
Publish swagger files to swagger UI server
See the APIs in swagger UI
//use
Client Developers browse via swagger UI
Know the calling patterns
Invoke them against targets and get JSON
Consume JSON in their native language
satya - 8/9/2017, 2:55:55 PM
OpenShift and Swagger and OpenAPI
OpenShift and Swagger and OpenAPI
satya - 8/9/2017, 3:19:42 PM
OpenAPI 3.0 Announcement: Let me see if it has anything in it
OpenAPI 3.0 Announcement: Let me see if it has anything in it
satya - 8/9/2017, 3:21:57 PM
Here are 3.0 enhancements
The overall structure of the specification was refactored for better reusability
Added Support for describing callbacks
Links to express relationships between operations
The JSON schema includes support for: oneOf, anyOf and not
Improved parameter descriptions, including the ability to use a schema
Better support for multipart document handling
Cookie parameters are in; dataForm parameters are out
Body parameters have their own entity
Better support for content-type negotiation
The security definitions have been simplified and enhanced
satya - 8/9/2017, 3:23:38 PM
Work horse of swagger
Some of the tools Swagger has produced are the Swagger UI and the Swagger Editor. The Swagger UI gave life to the OpenAPI Specification (formerly the Swagger Specification), allowing users to visualize and interact with the API in a format that?s easy to read and understand. The Swagger Editor, another popular open source project, is the de facto open source editor for designing APIs in the OpenAPI Specification. These are just some of the many tools Swagger continues to develop and grow to allow developers and consumers to take advantage of the OAS.
satya - 8/9/2017, 3:38:49 PM
Key websites
Open API home page: This is a very high level site pointing to swagger home page or to github where the spec is hosted. This is acting like a consortium news site. Links to a number of blogs and presentations may be worth looking at.
Swagger.io This is the main swagger site by the parent company. You will find implementation details for swagger editor, UI, and other tools. Documentation about the respective tools and the usual blog.
JSON Schema: Home page of JSON Schema. As a swagger file is JSON and its objects where the APIs are described are JSON elements the language of Swagger may be a subset of JSON Schema. More over for your own REST APIs you may want to check their validity through JSON Schema tools.
Swagger Hub: Appears to be a cloud based dictionary for your services where you can design them, provide documentation, define end points etc. Has a pricing model of free for single users and accounts for companies and teams. May push the stubs for servers and clients to github repositories. Probably something like this is required for "onpremise" solutions, but again the API managers are supposed to do that. Not sure what the cross section is.
Swagger tools: Lists an array of open source swagger tools. You will see tools for Go, Clojure, Java etc.
satya - 8/9/2017, 4:21:11 PM
How is security handled in OpenAPI and swagger Spec
How is security handled in OpenAPI and swagger Spec
Search for: How is security handled in OpenAPI and swagger Spec
satya - 8/9/2017, 4:21:36 PM
How is swagger used in large companies?
How is swagger used in large companies?