Today, I will introduce you to Swagger, a tool used in daily development. Swagger is a RESTful document generation tool.
The official description is 「The Best APIs are Built with Swagger Tools」 very domineering.
Swagger can be used in multiple language frameworks. For example, the flask framework under Python has "flask-restful-swagger", the Django framework "django-rest-swagger", and even tornado is available, but the usage is much less than the previous two.
Since swagger is powerful and there are so many integrated tools, today we mainly understand swagger-ui.
Why use swagger-ui
There is often a saying in the programming world, two things that programmers hate most:
1. Write notes and documents 2. Others do not write notes or documents.
why would you say so? Because it is troublesome to manage document annotations, API updates often occur, documents are still old, and various synchronization inconsistencies occur. It causes a lot of problems and delays each other's time, so everyone doesn't like to write documentation comments.
The main reason for using swagger is that it can reduce the synchronization problem of our front-end and back-end development documents. Swagger can automatically generate API documents from our code comments to facilitate front-end docking.
Secondly, it can display the list of all our interfaces, which is very convenient for us to debug the front and back interfaces. The front-end student docking interface can be operated directly on the page, and there is no need to switch between network tools such as postman and PAW, which is very simple and convenient.
Below I come to an official preview data table definition:
Django swagger installation and use
Next, let's talk about the installation and use process. Since we are mainly Python-based, we will introduce swagger-ui. Here, we will briefly introduce the use of Django:
pip install django-rest-swagger
要求： Django 1.8+ Django REST framework 3.5.1+ Python 2.7, 3.5, 3.6
in INSTALLED_APPS
INSTALLED_APPS = ( ... 'rest_framework_swagger', )
Add document address:
from django.conf.urls import urlfrom rest_framework_swagger.views import get_swagger_view schema_view = get_swagger_view(title='Pastebin API') test_urlpatterns = [ url(r'^$', schema_view) # Here you customize the document directory]#In this, we need to pay attention that it is used locally or in a test environment. It cannot be used online. The easiest way is the one I mentioned before. Judge the current environment through environment variables to add this test_urlpatterns. if current_env not in ['product','staging']: url_patterns = url_patterns + test_urlpatterns
The final result is a similar effect:
If you cooperate with Django-filter, it will be more convenient to perform front-end screening tests, almost between raising your hands for the XXX management page. Swagger and Django-REST-Framework can be said to greatly improve the speed of back-end write addition, deletion and modification (CRUD) and completion of docking.
Use in other languages
Swagger is not only used in Python, but swagger can be used in other language frameworks. I recommend everyone to use it, regardless of whether it is a Python programmer or not.
Address of other language tool integration:https://swagger.io/tools/open-source/open-source-integrations/
I don't know how many companies there are. Every time the API is updated, the documentation is not updated, which causes inconsistencies in the docking. Anyway, I have heard feedback from friends around me.
If you find that your company has this situation, swagger quickly.
The above is my introduction to swagger-ui. Actual swagger tools have two other powerful tools, swagger-editor and swagger-codegen. If you are interested, you can find out for yourself.