0
# Swagger Node CLI
1

2
Swagger Node CLI is a comprehensive command-line interface 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. The tool enables developers to specify, build, and test APIs from the very beginning on their laptop, allowing for iterative design changes without rewriting implementation logic.
3

4
## Package Information
5

6
- **Package Name**: swagger
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install -g swagger`
10

11
## Core Imports
12

13
For programmatic usage of internal modules:
14

15
```javascript
16
// Command modules
17
const { convert, validate } = require('swagger/lib/commands/commands');
18
const project = require('swagger/lib/commands/project/project');
19

20
// Utility modules
21
const cli = require('swagger/lib/util/cli');
22
const spec = require('swagger/lib/util/spec');
23
const browser = require('swagger/lib/util/browser');
24
```
25

26
## Basic Usage
27

28
Primary usage is through CLI commands:
29

30
```bash
31
# Create a new Swagger project
32
swagger project create my-api --framework express
33

34
# Start development server
35
cd my-api
36
swagger project start
37

38
# Edit API specification
39
swagger project edit
40

41
# Validate Swagger document
42
swagger validate api/swagger/swagger.yaml
43

44
# Convert Swagger 1.2 to 2.0
45
swagger convert old-api.json > new-api.yaml
46
```
47

48
## Architecture
49

50
Swagger Node CLI is built around several key components:
51

52
- **CLI Interface**: Two main binaries (`swagger` and `swagger-project`) providing complete command-line functionality
53
- **Project Management**: Full project lifecycle support from creation to testing and deployment
54
- **Swagger Editor Integration**: Embedded browser-based editor with real-time validation
55
- **Multi-Framework Support**: Built-in templates and configurations for Express, Hapi, Restify, Sails, and Connect
56
- **Validation System**: Comprehensive Swagger specification validation with detailed error reporting
57
- **Development Server**: Integrated server with hot reloading, mocking, and debugging capabilities
58

59
## Capabilities
60

61
### Project Management
62

63
Complete project lifecycle management including creation, configuration, development server, and testing.
64

65
```bash { .api }
66
# Create new project
67
swagger project create [name] [--framework <framework>]
68

69
# Start development server  
70
swagger project start [directory] [--debug] [--debug-brk] [--mock] [--open] [--node-args <args>]
71

72
# Verify project configuration
73
swagger project verify [directory] [--json]
74

75
# Run project tests
76
swagger project test [directory_or_file] [--debug] [--debug-brk] [--mock]
77

78
# Generate test templates
79
swagger project generate-test [directory] [--path-name <path>] [--test-module <module>] [--assertion-format <type>] [--force] [--load-test <path>]
80
```
81

82
[Project Management](./project-management.md)
83

84
### Swagger Editor Integration
85

86
Browser-based Swagger editor with real-time validation and file synchronization.
87

88
```bash { .api }
89
# Open Swagger editor
90
swagger project edit [directory] [--silent] [--host <host>] [--port <port>]
91

92
# Open project in browser
93
swagger project open [directory]
94
```
95

96
[Editor Integration](./editor-integration.md)
97

98
### Document Validation and Conversion
99

100
Swagger document validation and format conversion utilities.
101

102
```bash { .api }
103
# Validate Swagger document
104
swagger validate [swaggerFile] [--json]
105

106
# Convert Swagger 1.2 to 2.0
107
swagger convert <swaggerFile> [apiDeclarations...] [--output-file <fileName>]
108

109
# Open Swagger documentation
110
swagger docs
111
```
112

113
[Validation and Conversion](./validation-conversion.md)
114

115
### Programmatic API
116

117
Internal modules for programmatic usage in Node.js applications.
118

119
```javascript { .api }
120
// CLI utilities
121
const cli = require('swagger/lib/util/cli');
122

123
// Swagger specification validation  
124
const spec = require('swagger/lib/util/spec');
125

126
// Browser integration
127
const browser = require('swagger/lib/util/browser');
128

129
// Network utilities
130
const net = require('swagger/lib/util/net');
131

132
// Feedback system
133
const feedback = require('swagger/lib/util/feedback');
134

135
// Project management
136
const project = require('swagger/lib/commands/project/project');
137

138
// Command execution
139
const commands = require('swagger/lib/commands/commands');
140
```
141

142
[Programmatic API](./programmatic-api.md)
143

144
## Framework Support
145

146
Supported Node.js frameworks and their configurations:
147

148
- **Connect**: Base framework with middleware support
149
- **Express**: Express.js framework (overlay on Connect)
150
- **Hapi**: Hapi.js framework (overlay on Connect)
151
- **Restify**: Restify framework (overlay on Connect)  
152
- **Sails**: Sails.js framework with custom templates
153

154
## Test Configuration
155

156
Supported test frameworks and assertion libraries:
157

158
- **Test Modules**: `supertest`, `request`
159
- **Assertion Types**: `expect`, `should`, `assert`
160
- **Dependencies**: Automatically managed test dependencies including `mocha`, `chai`, `z-schema`