Skip to main content


Project description


Command-line interface (CLI) for making Swagger 2.0 projects easier to maintain
by breaking the paths and definitions out into discrete folders and files in OpenAPI Specification 2.0 format


Install and update using pip
$ pip install specd --upgrade
<h1>specd Components</h1>

- Structure
├── definitions
│ ├── Foo.yaml
│ └── Bar.yaml
└── paths
├── foo
│   └── {fooId}
│ ├── get.yaml
│ └── post.yaml
├── etc ...
└── etc ...
The paths and definitions of the specification file get broken out into
separate directories. The `paths` directory contains OpenAPI specs for every method that was defined in the original specification file. In this example, the swagger definition for the API's `GET` method that would be found at example URL `{fooId}/`, lives in `paths/foo/{fooId}/get.yaml`
The definitions of the specd are used as models to populate response fields, request body fields, and really anything else in the Swagger UI that requires a model of an object

- yaml and json Spec Files
All specification files are in the OpenAPI Specification 2.0 format. Below are examples of a `path`, `definition`, `.yaml` specification files that correspond with the example directory structure above.

__`get.yaml` - path__
description: Returns a single pet
operationId: get_foo_by_fooId
- application/json
- description: ID of pet to return
format: int32
in: path
name: fooId
required: true
type: integer
description: successful operation
$ref: '#/definitions/Foo' #Reference to the Foo model in definitions that is returned on response
description: Invalid bar supplied
description: foo object not found
- foo

__`Foo.yaml` - definition__
$ref: "#/definitions/Bar"
format: int32
type: integer
type: string
type: array
type: string
title: Foo
type: object
<h1>Core Features</h1>

- Converting a Specification File to a specd: `convert`
`convert` takes a swagger specification file as input and an output
directory as arguments, and creates a specd directory with the following

<h5>Command Options</h5>

| Command Options | Description | Default | Values |
| `-f, --format` | specify the format of the files in the output specd | `yaml` | `json` or `yaml` |


To get the specification file that defines the Swagger Petstore UI at <>, perform a wget to download the specification.json file, and then perform a convert on it
$ wget ""
$ specd convert ./swagger.json ~/petstore/
By specifying the output directory to be `~/petstore/`, specd will automatically create this directory if it does not already exist, and create a `specs` directory within it that contains a `specd.yaml` file, a `paths` directory, and a `definitions` directory.
├── petstore
│ └── specs
│ ├── definitions [not opening dir to save space]
│ │ ├── ApiResponse.yaml
│ │ ├── Category.yaml
│ │ ├── Order.yaml
│ │ ├── Pet.yaml
│ │ ├── Tag.yaml
│ │ └── User.yaml
│ ├── paths
│ │ ├── pet
│ │ │ └── ... [omitting subdirs to save space]
│ │ ├── store
│ │ │ └── ... [omitting subdirs to save space]
│ │ └── user
│ │ └── ... [omitting subdirs to save space]
│ └── specd.yaml
└── swagger.json

- Generating a Specification File: `generate`
`generate` is the inverse of the `convert` command. It takes a specd directory
and an output file as arguments, and generates a swagger specification file
from the path and definition files of the specd directory

<h5>Command Options</h5>

| Command Options | Description | Default | Values |
| `-c, --case` | specify if operation names in specification file <br> should be converted to `snake_case` or `camelCase` | `snake` | `snake` or `camel`|


Continuing off of the example from the `convert` command, we can create a new specification file for the Swagger Petstore API in yaml format based off of our specd directory
$ specd generate ~/petstore/specs ~/new_generated_spec.yaml
$ cd ~
$ ls
petstore/ swagger.json new_generated_spec.yaml

- Running Swagger: `swagger`
`swagger` starts a flask app for Swagger UI, allowing you to view and test your API. This command must be run out of your specd directory in order to function properly.

<h5>Command Options</h5>

| Command Options | Description | Default | Values/Type |
|:------------------ |:------------------------------------------------------------------------------|:--------|:------------------------------|
| `-h,`<br> `--host` | specify the host name of the server you <br>wish to hit with your swagger app. <br> If `None` is given, then specd retrieves a <br>hostname from the `specd.yaml` file within the specd directory| `None` | Any `str` |
| `-n,` <br>`--name` | specify name of API | `None` | Any `str` |
| `-t, --target` | specify the target API endpoints that you wish to be displayed | `None` | Comma separated list of `str` |


$ cd ~/petstore/specs
$ specd swagger --name="swagger_petstore"
* Serving Flask app "" (lazy loading)
* Environment: swagger
* Debug mode: off
* Running on (Press CTRL+C to quit)

By simply doing a `CTRL+click` on the URL you receive from the command line, you can access and test your swagger specd.
<h1>Additional Utility Commands</h1>

- Comparing Specifications: `diff`
`diff` takes two swagger specification files as arguments, and displays path and
definition differences between the two

$ specd diff ~/swagger.json ~/new_generated_spec.yaml

- List Definitions and Paths: `ls`
`ls` can be run inside of a specd directory in order to display all definitions and paths for that spec


$ cd ~/petstore/specs
$ specd ls




/pet/findByStatus: get
/pet/findByTags: get
/pet/{petId}/uploadImage: post
/pet/{petId}: delete, get, post
/pet: post, put
/store/inventory: get
/store/order/{orderId}: delete, get
/store/order: post
/user/createWithArray: post
/user/createWithList: post
/user/login: get
/user/logout: get
/user/{username}: delete, get, put
/user: post

- Linting Path and Definition Files: `lint`
When a specification swagger file is first broken out into *definition* and *paths* directories using `convert`, the file may have contained fields and types that are not registered with bravado. Although this does not directly affect the API spec's ability to function, logging can become very cluttered, as whenever bravado encounters an unregistered field, it throws a warning message.

Running the `lint` command takes a path to a specd directory as its only argument. When it is executed, `lint` will recursively traverse every single path and definition .json/.yaml file in the specd directory and remove any lines that will cause bravado to throw warnings.


$ specd lint ~/petstore/specs

- Validate Specd Directory: `validate`
`validate` takes no arguments, and will verify if your current working directory is a valid specd directory
$ cd ~/petstore/specs
$ specd
> Successfully validated.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for specd, version 0.8.1
Filename, size File type Python version Upload date Hashes
Filename, size specd-0.8.1-py2.py3-none-any.whl (19.6 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size specd-0.8.1.tar.gz (40.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page