Package: sanic-openapi-ext
sanic-openapi-extsanic-openapi-extis a Python package that provides a simplified method for generating OpenAPI (Swagger) documentation from Marshmallow schemas in a Sanic web application. It offers an explicit mapping between Marshmallow fields and OpenAPI fields, which aids in the automatic generation of precise API documentation.FeaturesAutomatic generation of OpenAPI (Swagger) documentation from Marshmallow schemas.Handles different types of Marshmallow fields including basic types, complex types, dates, and numbers.Supports conversion of nested fields and lists.Installationpip install sanic-openapi-extQuick StartHere's a simple example of how to use sanic-openapi-ext:frommarshmallowimportSchema,fieldsfromsanic_openapi_extimportopen_api_schemasclassUserSchema(Schema):name=fields.Str()birthdate=fields.Date()# Generate OpenAPI schema from Marshmallow schemauser_openapi_schema=open_api_schemas(UserSchema())ExamplesInput/output simple schema objectParameter represents query params asExampleSchemaResponse represents json output asExampleSchemafrommarshmallowimportSchema,fieldsfromsanicimportSanic,responsefromsanic_openapi_extimportopen_api_schemas,open_api_schemas_paramsfromsanic_extimportopenapifromsanic_ext.extensions.openapi.definitionsimportResponseclassExampleSchema(Schema):name=fields.Str(required=True)age=fields.Integer(required=True)app=Sanic("MyHelloWorldApp")@app.get("/")@openapi.definition(parameter=open_api_schemas_params(ExampleSchema()),response=[Response(open_api_schemas(ExampleSchema(),is_json=True),status=200),],)asyncdefget_and_return_example_schema(request):result=ExampleSchema().dump({"name":"John Doe","age":42})returnresponse.json({"success":200,"result":result})Input schema object with enum, output - nested schema with enumParameter represents header params asExampleSchemaResponse represents json output as list ofExampleSchemafromenumimportEnumfrommarshmallowimportSchema,fieldsfromsanicimportSanic,responsefromsanic_openapi_extimportopen_api_schemas,open_api_schemas_paramsfromsanic_extimportopenapifromsanic_ext.extensions.openapi.definitionsimportResponseclassColor(Enum):RED=1GREEN=2BLUE=3classExampleSchema(Schema):text=fields.Str()color=fields.Enum(Color)classExampleListSchema(Schema):items=fields.List(fields.Nested(ExampleSchema))app=Sanic("MyHelloWorldApp")@app.get("/")@openapi.definition(parameter=open_api_schemas_params(ExampleSchema(),location="header"),response=[Response(open_api_schemas(ExampleListSchema(),is_json=True),status=200),],)asyncdefget_and_return_example_schema(request):result=ExampleListSchema().dump([{"text":"Lorem ipsum","color":1}],many=True)returnresponse.json({"success":200,"result":result})Mapping referenceBelow is a mapping table of how Marshmallow fields are converted into OpenAPI fields:Marshmallow FieldOpenAPI FieldDateTimedoc.DateTimeDatedoc.DateTimedoc.TimeInteger,Intdoc.IntegerFloatdoc.FloatDecimaldoc.StringString, Strdoc.StringBoolean, Booldoc.BooleanEnumdoc.SchemaListdoc.ArrayNesteddoc.ObjectNote:If themanyattribute of the Marshmallow schema is set toTrue, or if the inputmanyattribute isTrue, a doc.List will be returned.If the inputis_jsonattribute isTrue, a doc.JsonBody will be returned.If the field is of typefields.Enum, adoc.Schema, which accepts the enumeration, is returned.If the field is of typefields.List, the inner_field is accessed. If the inner_field is afields.Nested, adoc.Objectis returned with the properties of the nested schema. If the inner_fields belong to other types, adoc.Arrayis returned with the properties of the inner type.For fields not listed in the table,doc.Stringis used as a default.Please, remember that this mapping may vary according to the use and the specific need of the project.ContributeWe'd love for you to contribute to our source code and to makesanic-openapi-exteven better than it is today! Here are some ways you can contribute:by reporting bugsby suggesting new featuresby writing or editing documentationby writing specificationsby writing code (no patch is too small, fix typos, add comments, clean up inconsistent whitespace)by refactoring codeby closing issuesby reviewing patchesLicensesanic-openapi-ext is released under the MIT license.