Add support of separate schema per status code

[victorcrimea]

Now apiflask supports multiple @app.output decorators

• fixes Support multiple responses with different response codes and schemes #327

    @app.route("/lessons", methods=['GET'])
    @app.input(LessonsRequestSchema, location="querystring")
    @app.output(LessonSchema, 201, description="Single lesson")
    @app.output(LessonsResponseSchema, 244, description="list of lessons")
    def lessons(query):
        #implementation goes here
        pass
  

[greyli]

Thanks for working on this. I'm not sure if we should support using multiple output decorators. If we want to support adding examples for the non-main response, making some enhancements on the doc decorator seems like a better way to go. I will do some experiments this weekend.

[victorcrimea]

With the approach I proposed apiflask chooses the response schema based on the response code provided by the view function. We may allow explicit declaration of output schema having a special response type like this:

      @app.route("/lessons", methods=['GET'])
      @app.input(LessonsRequestSchema, location="querystring")
      @app.output(LessonSchema, 201, description="Single lesson")
      @app.output(LessonsResponseSchema, 244, description="list of lessons")
      @app.output(LessonsResponseBriefSchema, 244, description="list of lessons(brief form)")
      def lessons(query):
          #implementation goes here
          data = {......} 
          return ApiflaskResponse(data, 204, LessonsResponseBriefSchema)

This approach will allow to have multiple Schemas per response status. I don't advocate that this is a good way to design an API, but this is what OpenAPI 3 supports with oneOf, allOf, etc (https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/) and someone may move legacy API implementation to apiflask and have to deal with that.

[victorcrimea]

The reason I modified output decorator and not doc is that it already supports examples. So it was easier change.
What was the original idea having doc and output separately? I understand input is separate because it also provides input data validation, but why output is separate from doc?

[greyli]

What was the original idea having doc and output separately?

output will serialize the return value and generate the spec, while doc only changes the spec.

Support oneOf, allOf, and anyOf needs more work on the schema resolver (take a look at https://github.com/marshmallow-code/marshmallow-oneofschema). For the spec part, apispec already supports these schema combinator types (marshmallow-code/apispec#701).

I still don't think it's the right direction. Closing now.