apiflask

What's Changed

• Fix syntax error in usage.md by @uncle-lv in https://github.com/apiflask/apiflask/pull/518
• Fix typos in docs and docstrings by @GuodongH in https://github.com/apiflask/apiflask/pull/521
• Add a tip for auth.current_user by @uncle-lv in https://github.com/apiflask/apiflask/pull/520
• Update pyupgrade; use --py38-plus by @sloria in https://github.com/apiflask/apiflask/pull/530
• Add Python 3.12 classifier by @sloria in https://github.com/apiflask/apiflask/pull/529
• fix: correct the return type of abort() by @frostming in https://github.com/apiflask/apiflask/pull/533
• Remove override of set_class in Schema by @sloria in https://github.com/apiflask/apiflask/pull/531
• Reuse the File, Config field, and file-related validators from flask-marshmallow by @uncle-lv in https://github.com/apiflask/apiflask/pull/543
• Add support for a --quiet flag to the flask spec command by @tsokalski in https://github.com/apiflask/apiflask/pull/550
• Fix spec command for complex data types by @tsokalski in https://github.com/apiflask/apiflask/pull/549

New Contributors

• @sloria made their first contribution in https://github.com/apiflask/apiflask/pull/530
• @frostming made their first contribution in https://github.com/apiflask/apiflask/pull/533

Full Changelog: https://github.com/apiflask/apiflask/compare/2.1.0...2.1.1

Major features

Support adding decorators to the openapi endpoints

by @FarmerChillax in https://github.com/apiflask/apiflask/pull/508

You can the newly added config keys to add auth protect to the OpenAPI endpoints:

app.config['SPEC_DECORATORS'] = [app.auth_required(auth)]
app.config['DOCS_DECORATORS'] = [app.auth_required(auth)]

See the complete example here: https://github.com/apiflask/apiflask/blob/main/examples/openapi/custom_decorators/app.py

Allow adding multiple media types for a response

by @ricardogsilva in https://github.com/apiflask/apiflask/pull/495

@app.get("/pets/<int:pet_id>")
@app.input(Accept, location="headers")
@app.output(PetOut)  # still have a main response of media type 'application/json'
@app.doc(responses={
    200: {
        'description': 'Return the resource in either JSON or HTML',
        'content': {
            'text/html': {}  # have an additional media type for the main response
        }
    }
})
def get_pet(pet_id, headers_data):
    pet = pets[pet_id]
    # depending on the content of the `Accept` header we may return JSON or HTML
    if "html" in headers_data.get('accept'):
        result = render_template('pets/pet-detail.j2.html', pet=pet)
    else:
        result = pet
    return result

Support adding response headers schema

by @uncle-lv in https://github.com/apiflask/apiflask/pull/511

The app.output decorator now accepts a headers argument:

@app.output(PetSchema, headers=MyHeaderSchema)
def hello():
    pass

Add file validators FileSize and FileType for File field

by @uncle-lv in https://github.com/apiflask/apiflask/pull/485

from apiflask.validators import FileType, FileSize

class Image(Schema):
    image = File(validate=[FileType(['.png', '.jpg', '.jpeg', '.gif']), FileSize(max='5 MB')])

See the complete example here: https://github.com/apiflask/apiflask/blob/main/examples/file_upload/app.py

What's Changed

• Fix typo in fields doc: files -> files_data by @Nekoyue in https://github.com/apiflask/apiflask/pull/499
• Fix Flask version warning by @greyli in https://github.com/apiflask/apiflask/pull/502
• Allow adding multiple media types for a response by @ricardogsilva in https://github.com/apiflask/apiflask/pull/495
• Add more examples of default values, description and example by @sylvain-ri in https://github.com/apiflask/apiflask/pull/505
• feat: response headers schema by @uncle-lv in https://github.com/apiflask/apiflask/pull/511
• Support adding decorators to the openapi endpoints by @FarmerChillax in https://github.com/apiflask/apiflask/pull/508
• Fix base response schema inconsistency issue by @greyli in https://github.com/apiflask/apiflask/pull/515
• Add file validators for File field by @uncle-lv in https://github.com/apiflask/apiflask/pull/485

New Contributors

• @Nekoyue made their first contribution in https://github.com/apiflask/apiflask/pull/499
• @ricardogsilva made their first contribution in https://github.com/apiflask/apiflask/pull/495
• @sylvain-ri made their first contribution in https://github.com/apiflask/apiflask/pull/505
• @FarmerChillax made their first contribution in https://github.com/apiflask/apiflask/pull/508

Full Changelog: https://github.com/apiflask/apiflask/compare/2.0.2...2.1.0

What's Changed

• Loosen Flask version requirement to >= 2 and set up test for minimum dependency versions by @wlach in https://github.com/apiflask/apiflask/pull/479
• Add example application for file uploading by @uncle-lv in https://github.com/apiflask/apiflask/pull/476
• Fix typos in docs by @guspan-tanadi in https://github.com/apiflask/apiflask/pull/475
• Refine the basic usage chapter by @greyli in https://github.com/apiflask/apiflask/pull/471
• Fix token auth example by @greyli in https://github.com/apiflask/apiflask/pull/472

New Contributors

• @guspan-tanadi made their first contribution in https://github.com/apiflask/apiflask/pull/475
• @uncle-lv made their first contribution in https://github.com/apiflask/apiflask/pull/476
• @wlach made their first contribution in https://github.com/apiflask/apiflask/pull/479

Full Changelog: https://github.com/apiflask/apiflask/compare/2.0.1...2.0.2

What's Changed

• Fix typing and documentation for responses parameter on doc decorator by @tsokalski in https://github.com/apiflask/apiflask/pull/467
• Add Config field by @greyli in https://github.com/apiflask/apiflask/pull/469

Example usage:

from apiflask import APIFlask, Schema
from apiflask.fields import Config

app = APIFlask(__name__)
app.config['API_TITLE'] = 'Pet API'

class FooSchema(Schema):
    title = Config('API_TITLE')

New Contributors

• @tsokalski made their first contribution in https://github.com/apiflask/apiflask/pull/467

Full Changelog: https://github.com/apiflask/apiflask/compare/2.0.0...2.0.1

A new major release!

From APIFlask 2.0.0, all the arguments passed to the view function are keyword arguments. The data passed with the input decorator will be a keyword argument named {location}_data. For example, the name for the JSON input will be json_data:

@app.post('/pets')
@app.input(PetQuery, location='query')
@app.input(PetIn)  # equals to app.input(PetIn, location='json')
def create_pet(query_data, json_data):
    pass

You can set a custom argument name with arg_name:

@app.post('/pets')
@app.input(PetQuery, location='query')  # query_data
@app.input(PetIn, arg_name='pet')  # pet
def create_pet(query_data, pet):
    pass

Other enhancements and changes:

• Add FileSchema to generate an OpenAPI file response (#447).
• Support using {} to represent not only empty body (204) but also empty schema. Using {} or EmptySchema will not set the status code to 204 anymore (#453).
• Support setting a complete response OpenAPI spec through the app.doc(responses) parameter (i.e. responses={400: {'description': '', 'content': ...}}) (#327).

See the changelog for the full changes: https://apiflask.com/changelog/#version-200
See the migration guide when you start to migrate to 2.x: https://apiflask.com/migration_guide/#migrate-to-apiflask-2x

A new bugfix release!

• Fix typos in openapi.md by @pamelafox in https://github.com/apiflask/apiflask/pull/417
• Fix PyYAML import error by @greyli in https://github.com/apiflask/apiflask/pull/420

New Contributors

• @pamelafox made their first contribution in https://github.com/apiflask/apiflask/pull/417

Full Changelog: https://github.com/apiflask/apiflask/compare/1.3.0...1.3.1

What's New

There are three new features in this release.

• Support passing APISpec object to spec processor by @greyli in https://github.com/apiflask/apiflask/pull/412

from apiflask import APIFlask

app = APIFlask(__name__)
app.config['SPEC_PROCESSOR_PASS_OBJECT'] = True

class FooSchema(Schema):
    id = Integer()

@app.spec_processor
def update_spec(spec):
    spec.title = 'Updated Title'
    spec.components.schema('Foo', schema=FooSchema)  # add a schema manually
    return spec

• Add security_scheme_name to customize OpenAPI security key by @greyli in https://github.com/apiflask/apiflask/pull/411
  Example usage:

auth = HTTPTokenAuth(header="X-Example-Key", security_scheme_name="api_token")

Generated spec:

"securitySchemes":{"api_token":{"in":"header","name":"X-Example-Key","type":"apiKey"}}

• Support customizing the media/content type of the response by @greyli in https://github.com/apiflask/apiflask/pull/413

@app.post('/image')
@app.output(ImageOutSchema, content_type='image/png')
def get_image():
    pass

• Add docs for config SECURITY_SCHEMES by @greyli in https://github.com/apiflask/apiflask/pull/414
• Update requirements by @greyli in https://github.com/apiflask/apiflask/pull/415

Full Changelog: https://github.com/apiflask/apiflask/compare/1.2.3...1.3.0

What's Changed

• Bypass OpenAPI spec generation for view methods by @greyli in https://github.com/apiflask/apiflask/pull/407

Full Changelog: https://github.com/apiflask/apiflask/compare/1.2.2...1.2.3

What's Changed

• Remove the validation of input location by @mmdbalkhi in https://github.com/apiflask/apiflask/pull/397
• Support passing Function type config to SWAGGER_UI_CONFIG by @tkzt in https://github.com/apiflask/apiflask/pull/402
• Fix the not-iterable exception occurred when directly returning a custom class by @tkzt in https://github.com/apiflask/apiflask/pull/400
• Update requirements by @greyli in https://github.com/apiflask/apiflask/pull/404

Full Changelog: https://github.com/apiflask/apiflask/compare/1.2.1...1.2.2

APIFlask 1.2.1 add the support to generate the servers field automatically. It's useful when you run your application behind the reverse proxy with a prefix URL.

See the newly added docs for more details: Running the application behind a reverse proxy

Notice that the servers will not be set when the request context is unavailable (for example, generating the spec with the flask spec command).

Breaking changes

• Add apiflask.views.MethodView to replace flask.views.MethodView, raise error if
  using flask.views.MethodView (#341)

from apiflask.views import MethodView

• Change the status code of request validation error from 400 to 422 in OpenAPI docs (#345). Thanks @hjlarry

You can control this with the config key VALIDATION_ERROR_STATUS_CODE:

app.config['VALIDATION_ERROR_STATUS_CODE'] = 422

Bugfixes and enhancements

• Add Enum field from marshmallow 3.18.
• Fix OpenAPI spec generating for path parameters when path schema is provided (#350). Thanks @ndawn
• Add spec_plugins param to APIFlask class to support using custom apispec plugins (#349). Thanks @ndawn
• Improve the default bypassing rules to support bypass blueprint's static endpoint and
  Flask-DebugToolbar (#344, #369).
• Explicitly check if view_func.view_class is MethodViewType in add_url_rule (#379). Thanks @rod7760
• The schema fields are now in order by default, which ensures the output of flask spec is deterministic
  (#373).

Translation

Thanks @mmdbalkhi for working on the Persian translation of APIFlask docs.

One more bugfix release.

• Fix some tests and import statements for Flask 2.2 (#343). Thanks @hjlarry
• Pin Flask < 2.2 as a temp fix for the breaking changes of class-based view support (#341).

We still need to make a real fix for #341, any help will be appreciated.

A bugfix release.

• Fix the incorrect Elements router setting. Now the default router option value will be hash. #339

A bugfix release for Flask 2.2.

• Improve CI setup and test again Python 3.10 and 3.11 (#331).
• Fix the typing of APIFlask path parameters (#329). Thanks @jeamland
• Update MethodViewType usages for Flask 2.2 (#335). Thanks @z-t-y

A new feature release!

• Support more API docs: RapiDoc, Elements, and RapiPDF. Now the docs UI is controlled by the docs_ui parameter (#308):

from apiflask import APIFlask

# available docs_ui values: swagger-ui, redoc, elements, rapidoc, rapipdf
app = APIFlask(__name__, docs_ui='elements')

• The API docs will be available at /docs by default, and the /redoc path and the redoc_path parameter were deprecated and will be removed in 2.0.
• Allow the view function to return list as JSON (#322):

@app.route('/')
def index():
    return ['this', 'will', 'become', 'JSON']

P.S. This feature will also be available in Flask 2.2.

See the full changelog for more details: https://apiflask.com/changelog/#version-110

Another bugfix release.

• Combine custom security schemes (app.security_schemes) with existing values (issue #293).
• Add the missing path (view_args) to the valid request location list (issue #301)
• Fix the security scheme values to lowercase.

A bugfix release:

• Fix the async support for app.auth_required, app.input, and app.doc decorators (issue #288). Thanks @jiashuChen!
• Add example applications for token auth and basic auth. Thanks @z-t-y
• Fix various bugs in docs. Thanks @Tridagger, @z-t-y, @rice0208, @jiashuChen

APIFlask 1.0 is finally released! 🎉

• The changelog: https://apiflask.com/changelog/#version-100
• The milestone: https://github.com/greyli/apiflask/milestone/3
• Check out the complete documentation: https://apiflask.com/docs/

Retweet the announcement on Twitter to tell your friends this news:

https://twitter.com/apiflask/status/1521869484746702849

Thanks for all your support!

This version brings a breaking change:

The four standalone API decorators (i.e. input, output, doc, and auth_required) were moved to APIFlask and APIBlueprint classes. Now access them with your application or blueprint instance:

from apiflask import APIFlask

app = APIFlask(__name__)

@app.get('/')
@app.input(FooSchema)  # <-
@app.output(BarSchema)  # <-
def hello():
    return {'message': 'Hello'}

This makes it possible to access app instance in these decorators so we can support changing corresponding behaviors based on application attributes or configuration variables.

The old standalone decorators were deprecated since 0.12, and will be removed in the 1.0 version. Notice all the usage in the docs/examples are updated, you may want to upgrade APIFlask to update the usage in your app.

The next version will be 1.0.0. Stay tuned!

This version improves the error handling system, you can now write custom error classes based on HTTPError:

from apiflask import HTTPError

class PetNotFound(HTTPError):
    status_code = 404
    message = 'This pet is missing.'
    extra_data = {
        'error_code': '2323',
        'error_docs': 'https://example.com/docs/missing'
    }


@app.get('/pets/<pet_id>')
def get_pet(pet_id):
    pets = [1, 2, 3]
    if pet_id not in pets:
        raise PetNotFound
    return {'message': 'Pet'}

See more details in the newly added docs for error handling.