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.

Filename, size & hash SHA256 hash help File type Python version Upload date
apispec_clear_unusable-1.0.1-py3-none-any.whl (3.7 kB) Copy SHA256 hash SHA256 Wheel py3
apispec-clear-unusable-1.0.1.tar.gz (3.6 kB) Copy SHA256 hash SHA256 Source None

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