• This repository has been archived on 15/Sep/2022
  • Stars
    star
    3,969
  • Rank 11,001 (Top 0.3 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created over 13 years ago
  • Updated about 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Swagger module for node.js

Archived

This GitHub repository has been archived. The npmjs package swagger may be re-used at a later date for a different project. https://swagger.io/ may have similar or alternative functionality if you depend(ed) on this project.

Build Status NPM version Dependency Status devDependency Status

The swagger module provides tools for designing and building Swagger-compliant APIs entirely in Node.js. It integrates with popular Node.js servers, including Express, Hapi, Restify, and Sails, as well as any Connect-based middleware. With swagger, you can specify, build, and test your API from the very beginning, on your laptop. It allows you to change and iterate your design without rewriting the logic of your implementation.

alt text

Remember, one great thing about this approach is that all of the Swagger validation logic is handled for you, and all of the routing logic is managed through the Swagger configuration. You don't have to code (or recode!) any of that stuff yourself.

Your swagger API in five steps

1. Install the swagger module

Install using npm. For complete instructions, see the install page.

$ npm install -g swagger

2. Create a new swagger project

Use the CLI to create and manage projects. Learn more on the quick start page.

$ swagger project create hello-world

3. Design your API in the Swagger Editor

The interactive, browser-based Swagger Editor is built in. It provides Swagger 2.0 validation and endpoint routing, generates docs on the fly, and consumes easy-to-read YAML.

$ swagger project edit

screenshot of project editor

4. Write controller code in Node.js

Code your API's business logic in Node.js.

function hello(req, res) {
    var name = req.swagger.params.name.value || 'stranger';
    var hello = util.format('Hello, %s!', name);
    res.json({ "message": hello });
}

If you look at the Swagger file in the editor (shown in step 3 above), the x-swagger-router-controller element (line 17 in the editor screenshot) specifies the name of the controller file associated with the /hello path. For example:

    paths:
        /hello:
            x-swagger-router-controller: hello_world

Controller source code is always placed in ./api/controllers. So, the controller source file for this project is ./api/controllers/hello_world.js.

The operationId element specifies which controller function to call. In this case (line 19), it is a function called hello. Learn more.

5. Run the server

Run the project server.

$ swagger project start

Now, call the API!

It just works!

$ curl http://127.0.0.1:10010/hello?name=Scott
{ "message": "Hello, Scott!" }

Installing the swagger module

See the Installing swagger for details.

Using the swagger module

Go to the swagger module doc page. It includes all the information you need to get started.

About this project

This initiative grew out of Apigee-127, an API design-first development framework using Swagger. Apigee donated the code to create the swagger-node project in 2015.

Copyright 2016 Apigee Corporation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


More Repositories

1

swagger-ui

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
JavaScript
26,260
star
2

swagger-codegen

swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
Mustache
16,866
star
3

swagger-editor

Swagger Editor
JavaScript
8,842
star
4

swagger-core

Examples and server integrations for generating the Swagger API Specification, which enables easy access to your REST API
Java
7,372
star
5

swagger-js

Javascript library to connect to swagger-enabled APIs via browser or nodejs
JavaScript
2,607
star
6

swagger.io-docs

The content of swagger.io
Astro
1,560
star
7

swagger-parser

Swagger Spec to Java POJOs
Java
777
star
8

swagger-samples

Samples for the various Swagger projects under swagger-api
JavaScript
537
star
9

swagger-socket

Swagger Socket: A REST over WebSocket
Java
383
star
10

swagger-play

Java
330
star
11

swagger-codegen-generators

Mustache
284
star
12

swagger-petstore

Java
245
star
13

validator-badge

Validate your Swagger JSON/YAML today!
Java
210
star
14

swagger-inflector

Java
159
star
15

swagger-converter

OpenAPI/Swagger 2.0 to OpenAPI 3.0 Converter WebService
Shell
114
star
16

swagger-scala-module

Swagger support for scala
Scala
103
star
17

apidom

Semantic parser for API specifications
TypeScript
68
star
18

rails-petstore

Ruby
29
star
19

swaggerhub-maven-plugin

A simple maven plugin to access SwaggerHub hosting of OpenAPI/Swagger from a maven build process.
Java
29
star
20

swagger-play-sample-app

A sample play app which uses swagger plugin to make the age old pet store swagger compliant.
JavaScript
29
star
21

swagger2

For working out the Swagger 2 working group page
CSS
21
star
22

scalatra-sample-app

Shell
20
star
23

swagger-scala-sample-app

A fully-functioning, stand-alone Swagger server written in scala which demonstrates how to enable Swagger in your API.
Scala
20
star
24

swagger-form-editor

JavaScript
19
star
25

swaggerhub-gradle-plugin

Gradle plugin for SwaggerHub
Java
19
star
26

petstore-kafka

A demo site built on top of Kafka topics
JavaScript
13
star
27

swagger-editor-cra

This is forked Create React App that builds SwaggerEditor@5
JavaScript
10
star
28

swagger-async-httpclient

Scala
10
star
29

swagger-play-1.2

Scala
9
star
30

swagger-scala

Scala
8
star
31

swagger-schema-packaging

6
star
32

apidom-lsp-vscode

ApiDOM VS Code Extension
TypeScript
5
star
33

sway-worker

4
star
34

apidom-ls-client

Demo client for apidom-ls OpenAPI / AsyncAPI ApiDOM validation service
TypeScript
3
star
35

.github

Common Github files for the Swagger projects
3
star
36

swagger-codegen-test

1
star