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-
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` 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
. ├── definitions │ ├── Foo.yaml │ └── Bar.yaml └── paths ├── foo │ └── {fooId} │ ├── get.yaml │ └── post.yaml ├── etc ... └── etc ... -
All specification files are in the OpenAPI Specification 2.0 format. Below are examples of a
path,definition,.yamlspecification files that correspond with the example directory structure above.get.yaml- pathdescription: 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- definitionproperties: bar: $ref: "#/definitions/Bar" fooId: format: int32 type: integer data_entries: items: type: string type: array name: type: string title: Foo type: object
-
converttakes a swagger specification file as input and an output directory as arguments, and creates a specd directory with the followingCommand Options Description Default Values -f, --formatspecify the format of the files in the output specd yamljsonoryamlTo 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 aspecsdirectory within it that contains aspecd.yamlfile, apathsdirectory, and adefinitionsdirectory.. ├── 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 -
generateis the inverse of theconvertcommand. 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 directoryCommand Options Description Default Values -c, --casespecify if operation names in specification file
should be converted tosnake_caseorcamelCasesnakesnakeorcamelContinuing off of the example from the
convertcommand, 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
-
swaggerstarts 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 Description Default Values/Type -h,
--hostspecify the host name of the server you
wish to hit with your swagger app.
IfNoneis given, then specd retrieves a
hostname from thespecd.yamlfile within the specd directoryNoneAny str-n,--namespecify name of API NoneAny str-t, --targetspecify the target API endpoints that you wish to be displayed NoneComma separated list of str$ 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+clickon the URL you receive from the command line, you can access and test your swagger specd.
-
difftakes two swagger specification files as arguments, and displays path and definition differences between the two$ specd diff ~/swagger.json ~/new_generated_spec.yaml
-
lscan be run inside of a specd directory in order to display all definitions and paths for that spec$ 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
-
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
lintcommand takes a path to a specd directory as its only argument. When it is executed,lintwill 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 -
validatetakes no arguments, and will verify if your current working directory is a valid specd directory$ cd ~/petstore/specs $ specd > Successfully validated.