Wilson Mar bio photo

Wilson Mar

Hello!

Calendar YouTube Github

LinkedIn

Swagger (REST API specification)

Design your API for code generation

US (English)   Norsk (Norwegian)   Español (Spanish)   Français (French)   Deutsch (German)   Italiano   Português   Estonian   اَلْعَرَبِيَّةُ (Egypt Arabic)   Napali   中文 (简体) Chinese (Simplified)   日本語 Japanese   한국어 Korean

Overview

This tutorial is about making use of a formal specification for the communication between clients and servers.

There has been several changes of names and technologies in this subject area.

“REST API” is being replaced by “HTTP API”.

“Swagger” was renamed “OAS” (Open API Specifications).

What is Swagger/OAS?

Swagger Core is a Description Language (DL) for REST APIs. It provides:

  • a blueprint of layout,
  • a contract,
  • metadata, and
  • human-readable documentation.

The goal of Swagger is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

In other words, Swagger’s objective is to be a complete framework for describing, producing, consuming, and visualizing RESTful web services for developers to fully program clients calling them.

Swagger removes the guesswork in calling the service. This enables Swagger CodeGen to generate client code for different programming languages.

Swagger removes a barrier to enterprise adoption of REST API by making a larger number of REST APIs governable, shareable, and human-readeable.[1]

Who built Swagger?

Swagger originated from folks at Wordnik.com (the on-line English dictionary) by Reverb Technologies (helloreverb.com) which was absorbed by Inform.com, now a part of MongoDB.

The old URL http://github.com/wordnik/swagger-core/wiki now redirects to http://github.com/swagger-api/swagger-core/wiki.

On March, 2015, the testing company SmartBear acquired from Reverb the swagger.io website and SwaggerHub.com which provides an instance of swagger on a free platform for teams to collaborate on and coordinate across the entire workflow of an API’s lifecycle. SwaggerHub includes connectors for GitHub, DockerHub, and Ready! API. The site leverages a centralized definition to enable teams to work together to iteratively design, build, document, and manage an API.

The spec

On January 1, 2016, the Swagger Specification at version 2.0 was transferred to the Open API Initiative (OAI), and renamed to the OpenAPI Specification. To avoid confusion, many now refer to the spec as “Swagger (OpenAPI) 2.0”.

https://github.com/swagger-api is the group maintaining

  • swagger-core
  • swagger-spec
  • swagger-ui
  • swagger-codegen

PROTIP: Many prefer the visual spec at http://openapi-specification-visual-documentation.apihandyman.io (on Chrome browser) by Arnaud Lauret, the API Handyman.

Spec Markup in Code

In .NET Core C# code, use the Swashbuckle package in NuGet, Ahoy in GitHub.

One of the best free tutorials on defining a Swagger spec begins with this introduction also by Arnaud Lauret, the API Handyman.

There are on-line Swagger spec editors at:

If you fell you’re struggling with this. Let us help you.

Spec Gen

Swagger’s focus was originally serving Node.js developers, but additional langagues now make use of Swagger.

Generating Swagger specs from legacy code can be the most time consuming aspect.

Some utilities that generate Swagger files based on annotations in server code:

  • Swashbuckle scans through C# WebAPI code and generates API website.

  • Doxygen is the de facto standard tool for generating documentation from annotated C source code. format comments in code can be picked up by the scanner.

  • Sandcastle

  • RDoc for Ruby code

  • AWS Chalice for Python. See this

  • JavaDocs generates code from comments in Java

Commentary about creating Swagger from code:

  • http://www.kobashicomputing.com/generating-documentation-from-c

Doxygen Gen

  1. Download the Doxygen UI.

Website Gen

Several tools generate API documentation in HTML for display on websites:

  • ReDoc

  • Microsoft Azure API Management, which charges.

  • Mashery’s IODocs is written to run on Node.js referencing a Redis key+value storage engine. See installation.

  • The Enunciate REST API framework is an open-source Java-based Web API framework. It creates full HTML documentation of the services it generates, where the documentation is assembled from JavaDocs comments.

Dependencies

Swagger Core stores JAX-RS API designs in JSON files from which Swagger UI dynamically generates beautiful HTML documentation.

Swagger makes use of Jackson, the multi-purpose Java library for processing JSON data format.

Swagger-core explains the use of maven build.

Sample endpoint

Format

The standard Swagger spec doesn’t support some features. So vendor

  • Request body examples (mock server is generating them from Schema) https://help.apiary.io/tools/mock-server

  • Example values of HTTP headers

  • Multiple requests

Converters to GraphQL

http://stackoverflow.com/questions/38339442/json-schema-to-graphql-schema-converters

https://github.com/yarax/swagger-to-graphql

Videos

Communicate to others

More on API Microservices

This is one of a series:

Swagger (REST API specification) was published on .