specd

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

Installing

Install and update using pip

$ pip install specd --upgrade

specd Components

• Structure

   .
   ├── definitions
   │   ├── Foo.yaml
   │   └── Bar.yaml
   └── paths
   	├── foo
   	│   └── {fooId}
   	│	├── get.yaml
   	│	└── post.yaml
   	├── etc ...
   	└── etc ...

  Paths

  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 `hostname.io/foo/{fooId}/`, lives in `paths/foo/{fooId}/get.yaml`

  Definitions

  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
   produces:
      - application/json
   parameters:
  - description: ID of pet to return
   format: int32
   in: path
   name: fooId
   required: true
   type: integer
  responses:
   '200':
     description: successful operation
     schema:
       $ref: '#/definitions/Foo'  #Reference to the Foo model in definitions that is returned on response
   '400':
     description: Invalid bar supplied
   '404':
     description: foo object not found
   tags:
      - foo

  Foo.yaml - definition

   properties:
     bar:
     $ref: "#/definitions/Bar"
   fooId:
     format: int32
     type: integer
   data_entries:
     items:
       type: string
     type: array
   name:
    type: string
   title: Foo
   type: object

Core Features

• 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

  Command Options

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

  Example

  To get the specification file that defines the Swagger Petstore UI at https://petstore.swagger.io/, perform a wget to download the specification.json file, and then perform a convert on it

  $ wget "http://petstore.swagger.io/v2/swagger.json" 
  $ 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

  Command Options

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

  Example

  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.

  Command Options

  Command Options	Description	Default	Values/Type
  -h, --host	specify the host name of the server you wish to hit with your swagger app. If None is given, then specd retrieves a hostname from the specd.yaml file within the specd directory	None	Any str
  -n, --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

  Example

  $ cd ~/petstore/specs
  $ specd swagger --name="swagger_petstore"
    * Serving Flask app "specd.app" (lazy loading)
    * Environment: swagger
    * Debug mode: off
    * Running on http://127.0.0.1:5000/ (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.

Additional Utility Commands

• Comparing Specifications: diff

  diff takes two swagger specification files as arguments, and displays path and definition differences between the two

  Example

  $ 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

  Example

  $ cd ~/petstore/specs
  $ specd ls
  
     Definitions:
  
     	  ApiResponse
     	  Category
     	  Order
     	  Pet
     	  Tag
     	  User
  
       Paths:
  
       	/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.

  Example

  $ 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.