How to use custom YAML file as API documentation in Django REST Framework?

Asked 10/6, 2020 at 5:29 Answered 6/5 at 10:24

django django-rest-framework yaml schema.yml

I need to add API documentation to my project. I wrote my custom schema using swagger editor and now I have a YAML file as follows:

swagger: "2.0"
info:
  description: "This is the documentation of Orion Protocol API"
  version: "1.0.0"
  title: "Orion Protocol API"
host: "127.0.0.1:8000"
basePath: "/api/"
paths:
  /api/decode:
    post:
      tags:
      - "pet"
      summary: "Decode the payload"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Packet data"
        required: true
        schema:
          $ref: "#/definitions/PacketData"
      responses:
        "405":
          description: "Invalid input"

  /api/encode:
   post:
     description: "Encoding configuration parameters for the devices"
     produces:
     - "string"
     parameters:
     - in: "body"
       name: "body"
       description: "Addresses and values of configuration parameters"
      required: true
       schema:
         $ref: "#/definitions/ConfigPayload"
     responses:
       "405":
         description: "Invalid input"


  definitions:
    PacketData:
      type: "object"
      required:
      - "payload"
      properties:
     payload:
       type: "string"
       description: "Packet string starting with 78"
       example: "78010013518BB325140400000500000AAA0000002A6E0000004AC05D00006A00000000"
    ConfigPayload:
        type: "object"
       properties:
          Addresses of the configuration parameter:
            type: "string"
            description: "According to the documentation of configuration protocol"
            example: "542"

Now how can I add this to the project? Where it should locate in the project? May the views render this file? I need to have the following path:

urlpatterns = [
     path('documentation/', some-view-that-will-render-yaml)
]

Hogue answered 10/6, 2020 at 5:29 Comment(0)

I found a solution and it was pretty easy. We need to convert yaml to json and save it in static folder. Then: urls.py

urlpatterns =  [
    ...
    path('swagger-ui/', TemplateView.as_view(
        template_name='swagger-ui.html',
        extra_context={'schema_url': 'openapi-schema'}
    ), name='swagger-ui'),
]

templates/swagger-ui.html:

{% load static %}
<html>
  <head>
    <title>Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
    <script>

   const ui = SwaggerUIBundle({
    url: "{% static 'swagger.json' %}" ,
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIBundle.SwaggerUIStandalonePreset
    ]
  })
    </script>
  </body>
</html>

and save your custom schema as json in static folder. Works!

Hogue answered 10/6, 2020 at 8:24 Comment(0)

It is very useful guide! Thanks to author!I had the same problem, but need to use Redoc.That's why I leave my solution for Redoc case, based on answer of Aigerim Sadir

urls.py

urlpatterns = [
    path('redoc/',
         TemplateView.as_view(template_name='redoc.html'),
         name='redoc'
    ),
]

redoc.html

{% load static %}
<!DOCTYPE html>
<html>
  <head>
    <title>Redoc</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css? 
   family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <redoc spec-url="{% static '/redoc.json' %}"></redoc>
    <script 
      src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> 
    </script>
  </body>
</html>

Peashooter answered 6/5 at 10:24 Comment(0)

Recommended topics

Hot tags