在工作當(dāng)中，會遇到需要寫API文檔的情況。最開始，在網(wǎng)上搜現(xiàn)成的django-rest-swagger，用了之后發(fā)現(xiàn)，不是很好用，沒辦法一次成型的解決問題。后來，就直接本辦法，把yaml轉(zhuǎn)化成swagger的html，就是套django模板啦（render）。yaml語法和json宗旨是差不多的，都是list和dict的結(jié)合。swagger就是一種內(nèi)容特定化的yaml文件。
YAML的view如下（一個view函數(shù)）：
def yaml2html(request):
import yaml, json, sys
with open('templates/test.yaml', 'r') as stream:
try:
yaml_string = json.dumps(yaml.load(stream))
except yaml.YAMLError as e:
print(e)
return HttpResponse("Error!")
return render(request, 'yaml-template.html', {'yaml_string': yaml_string})
模板如下（html模板，替換字符串，記住要加 ‘|safe’）：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title> Swagger UI </title>
<link rel="stylesheet">
<link rel="stylesheet" type="text/css" >
<style>
html
{
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}
*,
*:before,
*:after
{
box-sizing: inherit;
}
body {
margin:0;
background: #fafafa;
}
</style>
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.2.2/swagger-ui-bundle.js"> </script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.2.2/swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
var spec = {{ yaml_string|safe }};
// Build a system
const ui = SwaggerUIBundle({
spec: spec,
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
window.ui = ui
}
</script>
</body>
</html>
YAML文件：
---
swagger: "2.0"
openapi: 3.0.0
info:
description: Book API
title: Book API
version: 0.0.0-alpha
schemes:
- http
servers:
- url: 'http://localhost:8080'
- url: 'http://localhost:8082'
paths:
'/books/books':
get:
summary: get all books.
description: Get All Books.
parameters:
- name: book_id
in: query
schema:
type: integer
required: false
description: Id of the book
tags:
- Books
responses:
'200':
description: Books retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/projectResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/projectRequest'
security:
- api_key: []
...
