Open API

Introduction to Open API

Search for: Introduction to Open API

Homepage: Open API

A 2015 article on Open API

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.

Open API presentations


2015
Under Linux foundation
Based on Swagger 2.0

Looks like a good starting point article


inputs
outputs
name
security
documentation
what ever else that may come

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

Looks like there is a swagger editor to write the documentation

Not sure why a dependency on node!

What is the difference between Swagger and OpenAPI?

Search for: What is the difference between Swagger and OpenAPI?

Where does swagger end and OpenAPI begin?

Search for: Where does swagger end and OpenAPI begin?

Apigee and OpenAPI

Search for: Apigee and OpenAPI

Mashery and OpenAPI

Search for: Mashery and OpenAPI

What are good swagger API editors?

Search for: What are good swagger API editors?

Critique of the OpenAPI and Swagger

Search for: Critique of the OpenAPI and Swagger

How do you scale Swagger for lot of APIs or microservices?

Search for: How do you scale Swagger for lot of APIs or microservices?

Why use another language like swagger when there is Javadoc?

Search for: Why use another language like swagger when there is Javadoc?


<Person> 
   <firstname/>
   <lastname/>
   <username/> //required
</person>

//Equivalent
definitions:
  Person:
     required: 
       username
     properties:
        firstname:
           type:string
...etc

//Then you can use
items:
  $ref: "#/definitions/Person"

Boy... JSON Schemas


{
    "$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"]
}

Here is a github book on JSON Schema

Show images for: How is swagger used in API development

What is swaggerhub?

Search for: What is swaggerhub?

How is swagger used in API development?

Search for: How is swagger used in API development?

An article on how to use swagger API


Swagger Editor
Swagger Codegen
Swagger UI

Here is a list of Swagger tools


//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

OpenShift and Swagger and OpenAPI

Search for: OpenShift and Swagger and OpenAPI

OpenAPI 3.0 Announcement: Let me see if it has anything in it

A swagger guide to 3.2

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

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.

Specs

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.

Docs and related sites

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.

On Github

Swagger Editor - Github

Swagger UI - Github

Swagger Codegen - Github

Open API 3.0 on Github

How is security handled in OpenAPI and swagger Spec

Search for: How is security handled in OpenAPI and swagger Spec

How is swagger used in large companies?

Search for: How is swagger used in large companies?