django-rest-framework VS redoc

for those wishing to use http3 with a Python web framework, the ASGI hypercorn[1] currently supports it.

made a Django example last week with a sample client based on the examples from aioquic[2]: https://github.com/djstein/django-http3-example

this example also includes the first pass at async Django REST Framework using adrift[3] based on these GitHub issues:

- https://github.com/encode/django-rest-framework/pull/8617

- https://github.com/encode/django-rest-framework/issues/8496

sources

[1]: https://github.com/pgjones/hypercorn

[2]: https://github.com/aiortc/aioquic

[2]: https://github.com/em1208/adrf

Inspired by popular REST API frameworks like Django REST Framework and FastAPI, I wanted to create an alternative for Next.js, that will handle type-safe validation of your Next.js API routes using object-schema libraries like Zod and Yup and generate the OpenAPI specifications and Swagger UI straight out of your business logic. Another heavy inspiration for this project was tRPC and I wanted to extend it's functionality for REST APIs, specifically.

djangorestframework

Django REST Framework configuration + Swagger with drf-yasg.

Django REST framework is a great toolkit for building Web APIs. It is hugely popular and simplifies building REST APIs in Django, offering tooling for model serialization, registering routes and even adding support for authentication. In future projects, I would consider using it.

> Sure you can do DDD in Django. But I do not find that framework inherently CQRS of SOA (not SOA due to it's monolithic nature).

Django has "apps", which--while they do run in the same process--aren't intended to use code from each other. They're supposed to have their own models/views/templates/migrations/etc. They're effectively different services, as long as you don't think a service has to be available at a different network address to be a different service (think of mounting different apps or microservices behind different URLs, for example).

Also, I wouldn't say Django is CQRS--CQRS is more or less a different phrasing of "JSON-RPC", which "REST" has become.

> Last Django app i saw sure had a lot of this boilerplate going. I saw this talk and thought: well this is finally a "framework" that allowes me to do away with serialization (as in: in this framework the amount of extra work you do for making the app an SPA is fairly minimal):

Eh, some people are highly allergic to any boilerplate, but like, the DRF example [0] has practically none.

That Elm video is interesting, but I'm skeptical of anything whose central claim is "I can easily turn front end data requests into SQL and back again in very few lines of code". There's just a lot of inherent complexity there, and my evidence is every mainstream ORM, plus all the "backend-as-a-service" products that are multi-1000s LOC. Then again I think SQL is a great (legendary, honestly) language and we should stop trying to replace it.

[0]: https://www.django-rest-framework.org/#example

+1 for Django. What I'd like to see even more is something that is on-par with Django Rest Framework. This library deals with so much that I had wished that existed in other frameworks in other languages. Viewsets, different parsers, auto-generated API docs, excellent validation guards, authentication and permissions, throttling, filtering, pagination, versioning, many many more, it's just an amazing piece of work.

If you want to see how Redoc will render your OpenAPI definition you can try it out online at https://redocly.github.io/redoc/.

Redoc is an open source tool to generate API reference documentation websites from OpenAPI definitions.

FastAPI for Python has an awesome way of doing this. It comes with two choices: Swagger and Redoc, the former being more interactive while the latter is (IMO) more visually appealing. I'm sure you could implement one of these using Spring.

Starlite has substantially enhanced OpenAPI (3.1) documentation - in fact, its the most complete autogenerated schema around, and it ships with Redoc, Swagger-UI and Stoplight-Elements static sites.

# This is an **example** API to demonstrate features of OpenAPI specification. # It doesn't cover all OpenAPI features. For more full example check out: https://github.com/APIs-guru/petstore_extended openapi: 3.0.1 info: version: '1.0.0' # Your API version # It can be any string but it is better to use semantic versioning: http://semver.org/ # Warning: OpenAPI requires the version to be a string, but without quotation marks YAML can recognize it as a number. title: Example.com # Replace with your API title # Keep it simple. Don't add "API" or version at the end of the string. termsOfService: 'https://example.com/terms/' # [Optional] Replace with an URL to your ToS contact: email: [email protected] # [Optional] Replace with your contact email url: 'http://example.com/contact' # [Optional] Replace with link to your contact form license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' x-logo: url: 'https://redocly.github.io/openapi-template/logo.png' # Describe your API here, you can use GFM (https://guides.github.com/features/mastering-markdown) here description: | This is an **example** API to demonstrate features of OpenAPI specification # Introduction This API definition is intended to to be a good starting point for describing your API in [OpenAPI/Swagger format](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md). It also demonstrates features of [create-openapi-repo](https://github.com/Redocly/create-openapi-repo) tool and [Redoc](https://github.com/Redocly/Redoc) documentation engine. So beyond the standard OpenAPI syntax we use a few [vendor extensions](https://github.com/Redocly/Redoc/blob/master/docs/redoc-vendor-extensions.md). # OpenAPI Specification The goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service. externalDocs: description: Find out how to create a GitHub repo for your OpenAPI definition. url: 'https://github.com/Rebilly/generator-openapi-repo' # A list of tags used by the definition with additional metadata. # The order of the tags can be used to reflect on their order by the parsing tools. tags: - name: Echo description: Example echo operations - name: User description: Operations about user servers: - url: 'http://example.com/api/v1' - url: 'https://example.com/api/v1' # Holds the relative paths to the individual endpoints. The path is appended to the # basePath in order to construct the full URL. paths: '/users/{username}': # path parameter in curly braces # parameters list that are used with each operation for this path parameters: - name: pretty_print in: query description: Pretty print response schema: type: boolean get: # documentation for GET operation for this path tags: - User # summary is up to 120 symbold but we recommend to be shortest as possible summary: Get user by user name # you can use GFM in operation description too: https://guides.github.com/features/mastering-markdown description: | Some description of the operation. You can use `markdown` here. # operationId should be unique across the whole specification operationId: getUserByName # list of parameters for the operation parameters: - name: username in: path description: The name that needs to be fetched required: true schema: type: string - name: with_email in: query description: Filter users without email schema: type: boolean # security schemas applied to this operation security: - main_auth: - 'read:users' # for oauth2 provide list of scopes here - api_key: [] responses: # list of responses '200': description: Success content: application/json: # operation response mime type schema: # response schema can be specified for each response $ref: '#/components/schemas/User' example: # response example username: user1 email: [email protected] '403': description: Forbidden '404': description: User not found # documentation for PUT operation for this path put: tags: - User summary: Updated user description: This can only be done by the logged in user. operationId: updateUser parameters: - name: username in: path description: The name that needs to be updated required: true schema: type: string security: - main_auth: - 'write:users' responses: '200': description: OK '400': description: Invalid user supplied '404': description: User not found # request body documentation requestBody: content: application/json: schema: $ref: '#/components/schemas/User' application/xml: schema: $ref: '#/components/schemas/User' description: Updated user object required: true /echo: # path parameter in curly braces post: # documentation for POST operation for this path tags: - Echo summary: Echo test description: Receive the exact message you've sent operationId: echo security: - api_key: [] - basic_auth: [] responses: '200': description: OK # document headers for this response headers: X-Rate-Limit: # Header name description: calls per hour allowed by the user schema: # Header schema type: integer format: int32 X-Expires-After: $ref: '#/components/headers/ExpiresAfter' content: application/json: schema: type: string examples: response: value: Hello world! application/xml: schema: type: string text/csv: schema: type: string requestBody: content: application/json: schema: type: string example: Hello world! application/xml: schema: type: string example: Hello world! description: Echo payload required: true # An object to hold reusable parts that can be used across the definition components: schemas: Email: description: User email address type: string format: test example: [email protected] User: type: object properties: username: description: User supplied username type: string minLength: 4 example: John78 firstName: description: User first name type: string minLength: 1 example: John lastName: description: User last name type: string minLength: 1 example: Smith email: $ref: '#/components/schemas/Email' headers: ExpiresAfter: description: date in UTC when token expires schema: type: string format: date-time # Security scheme definitions that can be used across the definition. securitySchemes: main_auth: # security definition name (you can name it as you want) # the following options are specific to oauth2 type type: oauth2 # authorization type, one of: oauth2, apiKey, http flows: implicit: authorizationUrl: 'http://example.com/api/oauth/dialog' scopes: 'read:users': read users info 'write:users': modify or remove users api_key: # security definition name (you can name it as you want) type: apiKey # The following options are specific to apiKey type in: header # Where API key will be passed: header or query name: api_key # API key parameter name basic_auth: # security definition name (you can name it as you want) type: http scheme: basic

I currently use https://github.com/typestack/routing-controllers and https://github.com/epiphone/routing-controllers-openapi with https://github.com/Redocly/redoc

Redoc is an open-source tool for generating documentation from OpenAPI (fka Swagger) definitions. There is a paid service with more features called Redocly, but for this project we are utilizing the open source redoc-cli tool.

FastAPI has documentation that is fully compatible with OpenAPI and JSONSchema, which is created automatically from Pydantic schemas and function parameters or GET variables. The user interface is provided by SwaggerUI and Redoc.

You can easily generate API docs for free with Redoc (https://redocly.github.io/redoc/) , SwaggerUI (https://swagger.io/tools/swagger-ui/) and many more so I am on the other side and think the the pricing is too high, especially the premium to use a custom domain.

What is the advantage of using your product to what is available for free except some CSS tweaks?