Как сгенерировать машиночитаемую спецификацию yaml существующего API, написанного на flask-restplus? - PullRequest
Новая
       52

Как сгенерировать машиночитаемую спецификацию yaml существующего API, написанного на flask-restplus?

0 голосов
/ 13 января 2019

У меня есть простой API, написанный с помощью flask-restplus: 

from flask import Flask
from flask_restplus import Resource, Api

app = Flask(__name__)                  #  Create a Flask WSGI application
api = Api(app)                         #  Create a Flask-RESTPlus API

@api.route('/hello')                   #  Create a URL route to this resource
class HelloWorld(Resource):            #  Create a RESTful resource
    def get(self):                     #  Create GET endpoint
        return {'hello': 'world'}

if __name__ == '__main__':
    app.run(debug=True)

Когда я перехожу к loacalhost:5000/ в браузере, я получаю базовую документацию по Swagger, но не могу найти, где взять машиночитаемое представление API в виде простого yaml, не должно ли оно также генерироваться автоматически?

1 Ответ

0 голосов
/ 13 января 2019

Я не смог найти информацию о "генерации документации Swagger Yaml" в официальных документах flask-restplus . Итак, я решил изучить исходный код и обнаружил, что класс Swagger реализует генерацию документации Swagger для экземпляра API.

Класс Swagger в исходном коде flask-restplus является оболочкой документации Swagger для экземпляра API. Все методы в этом классе предполагают, что данные API сериализуются в виде словаря JSON. Например, рассмотрим функцию as_dict() этого класса, которая сериализует полную спецификацию Swagger как сериализуемый диктат. Посмотрите на строку документации для этой функции: 

from flask import Flask
from flask_restplus import Resource, Api
from flask_restplus.api import Swagger

app = Flask(__name__)                  
api = Api(app)

swag = Swagger(api)
print(swag.as_dict.__doc__) 

#Output:
Output the specification as a serializable ``dict``.

    :returns: the full Swagger specification in a serializable format
    :rtype: dict

Возможно, я ошибаюсь, но исходный код предполагает, что документация API возвращается только как JSON, которая доступна по умолчанию в http://localhost:5000/swagger.json. Я не смог найти ничего для YAML.

Но есть обходной путь для создания документации YAML для вашего API. Я использовал библиотеки json и yaml, чтобы выгрузить ответ json из /swagger.json в YAML и сохранить его в yamldoc.yml. Вы можете вызвать это, перейдя на http://localhost:5000/swagger.yml. Полный код: 

from flask import Flask
from flask_restplus import Resource, Api
from flask_restplus.api import Swagger
import requests
import json, yaml

app = Flask(__name__)                  #  Create a Flask WSGI application
api = Api(app)                         #  Create a Flask-RESTPlus API

@api.route('/hello')                   #  Create a URL route to this resource
class HelloWorld(Resource):            #  Create a RESTful resource
    def get(self):                  
        return {'hello': 'world'}

@api.route('/swagger.yml')
class HelloWorld(Resource):    
    def get(self):
       url = 'http://localhost:5000/swagger.json'       
       resp = requests.get(url)
       data = json.loads(resp.content)    
       with open('yamldoc.yml', 'w') as yamlf:
           yaml.dump(data, yamlf, allow_unicode=True)
       return {"message":"Yaml document generated!"}


if __name__ == '__main__':
    app.run(debug=True)

Надеюсь, это поможет.

...