Demonstrating the use of OpenAPI Spec and Swagger tools to build REST APIs, documentation, and generated SDKs
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
api
codegen
docs
ng-demo
.gitignore
LICENSE
README.md

README.md

openapi-swagger-demo

This repo demonstrates the use of OpenAPI Spec and Swagger tools to build REST APIs, documentation, and generated SDKs. It was created to support my presentation on designing APIs with OpenAPI

Contents

The repo is broken into 4 sections.

/api A Sample API built with swagger-node. All the other sections require the API to be running.

/docs A documentation site using swagger-ui that runs off the OpenAPI spec on the sample API.

/codgen A Codegen example demonstrating how to build a TypeScript client SDK based on the sample API.

/ng-demo A sample Angular site that connects to our sample API via the codgen-built client SDK.

API

Contains a sample api generated by swagger-node.

To Run:

[sudo] npm install -g swagger
npm install api
swagger project start api

To Start OpenAPI Doc Editor:

swagger project edit api

Sample Query:

curl http://localhost:10010/lyrics?name=Paul

Codegen

Contains a compiled version of the codegen cli, as well as a sample install script for generating a typescript client library for our lyrics api.

Note: You'll need to have the api running before building the client library, as it will fetch the swagger info from http://localhost:10010/swagger.

Generate a TypeScript Library:

./codegen/gen-typescript.sh

ng-demo

Contains an Angular demo app that uses the codegen generated client library to connect to our api.

Note: You'll need the api running.

[sudo npm install -g @angular/cli
cd ng-demo
npm install
ng serve --open

Docs

Demo docs site that uses our OpenAPI spec served up via the api. This example uses swagger-ui-express. Also check out swagger-ui.

Note: Need the api running!

npm install docs
node docs/app.js

Then check out http://127.0.0.1:3006