pip install django-rest-swagger
2.快速搭建:
1)在Django的settings.py中:
INSTALLED_APPS = [
...
'rest_framework_swagger',
...
]
2)在urls.py中:
from rest_framework_swagger.views import get_swagger_view
schema_view = get_swagger_view(title='Pastebin API') #其中title='Pastebin API'为改rest api显示集合的名字(可自定义)
urlpatterns = [
……
url(r'^$', schema_view)
……
]
Spring Boot 集成 Swagger
1、添加依赖
Maven依赖示例:
2、在 Spring Boot 配置文件中添加配置参数。
3、添加配置类
如何使用
Swagger 默认会根据配置的包,扫描所有接口并生成对应的 API 描述和参数信息,但这样不是很直观,需要对每个接口和参数进行自定义描述。
常用的 Swagger 注解如下。
使用示例如:
http://localhost:8080/swagger-ui.html
打开 swagger-ui 界面,可以看到所有的 API 接口定义,也可以在上面发起接口测试。
34张架构史上最全技术知识图谱
默认的swagger-ui好用但是不够美观,为了让生成的文档更加可观,我们可以使用swagger-ui-layer 来美化。
swagger-ui-layer,基于layui 开源的swagger-ui的替换。界面大气,使用起来也很方便。swagger-ui-layer 依于swagger的功能,所以在原先项目中导入以下依赖即可
注意:
使用规则:
一、在返回对象类上中要使用注解@ApiModel(value="实体类对象", description="实体类描述"),对象字段上使用@ApiModelProperty(value=”字段说明“,required=”是否必填”)表示对model属性的说明
注意:@ApiModel value 不能同名,否则会导致参数乱窜.
二、@API使用在Controller类上,表明是swagger资源
@Api(value = "仓库管理controller", tags = {"仓库管理接口"})
三、在每个接口方法中使用注解@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”);表示一个http请求的 *** 作
四、 @RequestBody和@ApiImplicitParam不能共用
@RequestBody主要用来接收前端传递给后端的json字符串中的数据的,如果想要swagger显示出实体类的参数描述信息要在实体类上使用@ApiModel(value="")
原先:在接口方法中会使用@ApiImplicitParam(name = "vo", value = "用户实体类", paramType = "body", required = true, dataType = "UserVo") 但@RequestBody和@ApiImplicitParam注解,会使实体类参数描述信息显示不出来,所以@ApiImplicitParam适用于没有接收实体类参数的方法
五、 @ApiParam 用于 Controller 中方法的参数说明。如图所示。
六、如果接口中,实体参数的描述没有显示出来可以加上@ModelAttribute 注解
七、通过 @PathVariable 可以将 URL 中占位符参数绑定到控制器处理方法的入参中:URL 中的 {xxx} 占位符可以通过@PathVariable(“xxx“) 绑定到 *** 作方法的入参中。在swagger接口文档中,不会显示出这个占位符的具体信息,如下不会显示出这个id的说明
建议使用@ApiParam注解:
也可以使用@ApiImplicitParam对接收的参数进行解释
注意:
要改成这样
八、在使用@RequestParam注解,获得前台传递的值,一般要结合@ApiParam注解使用
欢迎分享,转载请注明来源:内存溢出
评论列表(0条)