Poszukuję szybkiego sposobu automatycznego tworzenia dokumentacji REST API z interfejsu API REST, który napisałem. Czy ktoś wie o narzędziach, które mogą to zrobić i w jaki sposób oznaczę kod?Jakie narzędzia są dostępne do automatycznego tworzenia dokumentacji API REST napisanego w kolbie?
Jakie narzędzia są dostępne do automatycznego tworzenia dokumentacji API REST napisanego w kolbie?
Odpowiedz
Polecam Ci Sphinx dodasz swoją dokumentację jako __doc__
i moduł Sfinks autodoc
generuje docs dla Ciebie (docs.python.org wykorzystuje również Sfinksa). Znacznik to reST
, podobny do Markdown
.
np .:
@app.route('/download/<int:id>')
def download_id(id):
'''This downloads a certain image specified by *id*'''
return ...
Jest to rozszerzenie Kolba: flask-autodoc dokumentacji auto specjalnie parsowania regułę trasy końcowego. Możesz dodać doc
dekorator, aby określić, które API chcesz Doc:
@app.route('/doc')
@auto.doc()
def documentation():
'''
return API documentation page
'''
return auto.html()
@app.route('/')
@auto.doc()
def welcome():
'''
Welcome API
'''
commit_hash = subprocess.check_output(["git", "rev-parse", "HEAD"])
commit_msg = subprocess.check_output(["git", "log", "-1", "--format=%s"])
date_time = subprocess.check_output(["git", "log", "-1", "--format=%cd"])
return "Welcome to VM Service Server. <br/>" \
"The last commit: %s<br/>Date: %s, <br>Hash: %s" % \
(commit_msg, date_time, commit_hash), 200
Prosta strona dokumentacji html jest tak:
Zdaję sobie sprawę, że jest to pewnego rodzaju opinia, ale ostrzegałbym ludzi przed kolby-autodoc. Rozszerzenie jest naprawdę niekompletne. Zaczyna się świetnie, i ustawia się tak, jak można by oczekiwać, ale efekt końcowy jest nijakie. Większość ludzi porzuci go dla sfinksa i zmarnuje kilka godzin na kolbie-autodoc. – melchoir55
Gdybym tylko widział to 30 minut temu ... +1 – Zeb
Czy mógłbyś wyjaśnić, dlaczego automatyczna kolba-autodoc jest niekompletna? Rzuciłem okiem na dokumentację i podobało mi się to znacznie bardziej niż np. Flask-RESTplus. – imolit
bardzo podoba mi Swagger ponieważ pozwala wygenerować API dokumentację poprzez dodanie kilku dekoratorów i komentarzy do twojego kodu. Dostępny jest Flask Swagger.
from flask import Flask
from flask.ext.restful import Api
from flask_restful_swagger import swagger
app = Flask(__name__)
api = swagger.docs(Api(app), apiVersion='1', api_spec_url="/api/v1/spec")
class Unicorn(Resource):
"Describing unicorns"
@swagger.operation(
notes='some really good notes'
)
def get(self, todo_id):
...
Następnie można zobaczyć swoje metody i notatki w interfejsie html prostu odwiedzając/api/v1/spec (służy ona potrzebna statycznego automatycznie). Możesz również po prostu uzyskać cały opis API w JSON i przeanalizować go w inny sposób.
- 1. Narzędzia do tworzenia dokumentacji dla API RPC
- 2. Jakie narzędzia są dostępne do dokumentowania wtyczek jQuery?
- 3. Jakie narzędzia są dostępne dla refaktoryzacji Ruby?
- 4. Jakie narzędzia do rejestrowania debugowania są dostępne w JavaScript?
- 5. Jakie narzędzia są dostępne do testowania wydajności instrukcji SQL?
- 6. Filtry interfejsu Facebook Graph API - Jakie opcje są dostępne?
- 7. Jakie są dobre przykłady bibliotek klientów REST API w JavaScript
- 8. Automatyzacja dokumentacji REST API dla tras
- 9. Jakie samodzielne analizatory składni Java są dostępne?
- 10. Jakie operatory matematyczne są dostępne w metaprogramowaniu
- 11. Jakie czcionki są dostępne w systemie Android?
- 12. Jakie narzędzia są dostępne do utworzenia pliku pomocy w Visual Studio 2010?
- 13. Jakie techniki/narzędzia są dostępne do odkrywania popularnych zwrotów w kawałkach tekstu?
- 14. Jakie narzędzia są dostępne w celu wyeksportowania notatnika do pliku PDF?
- 15. Jakie narzędzia są dostępne w celu dodania lokalizacji do projektu ASP.NET?
- 16. Jakie są dostępne biblioteki do tworzenia "ruchomych/żywych" interfejsów użytkownika w delphi?
- 17. Narzędzia do automatycznego upraszczających regexes
- 18. Jakie struktury danych drzewa javascript są dostępne?
- 19. Jakie narzędzia lub techniki są dostępne do "dataminowania" mojego repozytorium mercurialnego?
- 20. Jakie pliki COFF (pliki .OBj) są dostępne?
- 21. Narzędzia do tworzenia AnimatedVectorDrawable
- 22. Jakie narzędzia są dostępne do ustalenia, które zestawy .NET uległy zmianie od czasu ostatniej kompilacji?
- 23. Jakie narzędzia klienta są dostępne do zarządzania Amazon S3 i CloudFront?
- 24. Jakie wtyczki kompilatora scala są dostępne?
- 25. Jakie sterowniki MySQL są dostępne dla node.js?
- 26. Jakie są dostępne warianty warunku w pliku uiGridConstants.filter?
- 27. Jakie są najlepsze/popularne biblioteki do tworzenia aplikacji/skryptów CLI?
- 28. Jakie wtyczki są dostępne dla Eclipse?
- 29. Jakie źródła entropii są dostępne na heroku?
- 30. Narzędzia do skrobania stron internetowych/narzędzia dostępne w Ruby
Istnieje nawet moduł Sphinx o nazwie sphinxcontrib.autohttp.flask (http://pythonhosted.org/sphinxcontrib-httpdomain/#module-sphinxcontrib.autohttp.flask). –