Metadata-Version: 2.1
Name: specd
Version: 0.8.2
Summary: specd
Home-page: UNKNOWN
Author: Ian Maurer
Author-email: ian@genomoncology.com
License: MIT license
Description: <h1>specd</h1>
        
        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
        
        <h1>Installing</h1>
        
        Install and update using pip
        ```bash
        $ pip install specd --upgrade
        ```
        <h1>specd Components</h1>
        
        - Structure
          ---
        	```bash
        	.
        	├── definitions
        	│   ├── Foo.yaml
        	│   └── Bar.yaml
        	└── paths
            	├── foo
            	│   └── {fooId}
            	│	├── get.yaml
            	│	└── post.yaml
        		├── etc ...
            	└── etc ...
        	```
        	<h5>Paths</h5>
        	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`
        	<h5>Definitions</h5>
        	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__
         	```yaml
         	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__
         	```yaml
         	properties:
         	  bar:
              $ref: "#/definitions/Bar"
            fooId:
              format: int32
              type: integer
            data_entries:
              items:
                type: string
              type: array
            name:
             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` |
            
            <h5>Example</h5>
            
            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
            ```bash
            $ 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.
            ```bash
            .
            ├── 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`|
            
            <h5>Example</h5> 
             
            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
            ```bash
            $ 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` |
        
        	<h5>Example</h5>
        	
            ```bash
            $ 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.
        <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
            <h5>Example</h5>
            
            ```bash
            $ 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
            
             <h5>Example</h5>
            
             ```bash
             $ 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.
             
             <h5>Example</h5>
             
             ```bash
             $ 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 
             ```bash
             $ cd ~/petstore/specs
             $ specd
             > Successfully validated.
             ```
        
        
        
Keywords: Swagger Open API Specification Bravado
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Description-Content-Type: text/markdown
