Skip to main content

Plugin for apispec which helps reusing the documentation on a muti-endpoint function/method.

Project description

apispec-clear-unusable

Plugin for apispec which helps reusing the documentation on a muti-endpoint function/method.

Example with flask-restful

from apispec import APISpec
from flask import Flask, jsonify
from flask_restful import Resource, Api
from marshmallow import Schema, fields

# Create an APISpec
spec = APISpec(
    title='Random swagger Petstore',
    version='1.0.0',
    plugins=[
        'apispec.ext.flask',
        'apispec.ext.marshmallow',
        'brunoais.apispec.ext.clear_unusable',
    ],
)

# This example uses flask but it also works with other frameworks
app = Flask(__name__)
api = Api(app)

class RandomPet(Resource):

    def get(self, species=None, race=None):
        """A cute random furry animal.
        ---
        description: Get a random pet
        parameters:
            - in: path
              name: species
              type: string
              description: The species of the animal to be randomly selected
        parameters:
            - in: path
              name: race
              type: string
              description: The race of the animal to be randomly selected
        responses:
            200:
                description: A pet to be returned
                schema: PetSchema
        """
        return get_random_pet(species=species, race=race), 200


api.add_resource(RandomPet, '/pets/random', endpoint='randompet')
api.add_resource(RandomPet, '/pets/<species>/random', endpoint='randompet_species')
api.add_resource(RandomPet, '/pets/<species>/races/<race>/random', endpoint='randompet_species_race')

spec.definition('Category', schema=CategorySchema)
spec.definition('Pet', schema=PetSchema)

with app.test_request_context():
    spec.add_path(view=random_pet)

Output becomes

definitions:
	#...
parameters: {}
paths:
  /pets/random:
    get:
      description: Get a random pet
      parameters: []
      responses:
        200:
          description: A pet to be returned
          schema: {$ref: '#/definitions/Pet'}
  /pets/{species}/random:
    get:
      description: Get a random pet
      parameters:
      - {description: The species of the animal to be randomly selected, in: path,
        name: species, required: true, type: string}
      responses:
        200:
          description: A pet to be returned
          schema: {$ref: '#/definitions/Pet'}
  /pets/{species}/races/{race}/random:
    get:
      description: Get a random pet
      parameters:
      - {description: The species of the animal to be randomly selected, in: path,
        name: species, required: true, type: string}
      - {description: The race of the animal to be randomly selected, in: path, name: race,
        required: true, type: string}
      responses:
        200:
          description: A pet to be returned
          schema: {$ref: '#/definitions/Pet'}
swagger: '2.0'

Installation

pip install apispec-clear-unusable

License

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

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 apispec-clear-unusable, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size apispec_clear_unusable-1.0.1-py3-none-any.whl (3.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size apispec-clear-unusable-1.0.1.tar.gz (3.6 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page