精华内容
下载资源
问答
  • 自动生成接口文档

    2019-10-07 00:14:02
    自动生成接口文档 REST framework可以自动帮助我们生成接口文档。 接口文档以网页的方式呈现。 自动接口文档能生成的是继承自APIView及其子类的视图。 安装依赖 REST framewrok生成接口文档需要coreapi库的支持...

    自动生成接口文档

    REST framework可以自动帮助我们生成接口文档。

    接口文档以网页的方式呈现。

    自动接口文档能生成的是继承自APIView及其子类的视图。

    安装依赖

    REST framewrok生成接口文档需要coreapi库的支持。

    pip install coreapi

    设置接口文档访问路径

    在总路由中添加接口文档路径。

    文档路由对应的视图配置为rest_framework.documentation.include_docs_urls

    参数title为接口文档网站的标题。

    from rest_framework.documentation import include_docs_urls
    
    urlpatterns = [
        ...
        path('docs/', include_docs_urls(title='站点页面标题'))
    ]

    文档描述说明的定义位置

    1) 单一方法的视图,可直接使用类视图的文档字符串,如

    class BookListView(generics.ListAPIView):
        """
        返回所有图书信息.
        """

    2)包含多个方法的视图,在类视图的文档字符串中,分开方法定义,如

    class BookListCreateView(generics.ListCreateAPIView):
        """
        get:
        返回所有图书信息.
    
        post:
        新建图书.
        """

    3)对于视图集ViewSet,仍在类视图的文档字符串中封开定义,但是应使用action名称区分,如

    class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
        """
        list:
        返回图书列表数据
    
        retrieve:
        返回图书详情数据
    
        latest:
        返回最新的图书数据
    
        read:
        修改图书的阅读量
        """

    访问接口文档网页

    两点说明:

    1) 视图集ViewSet中的retrieve名称,在接口文档网站中叫做read

    2)参数的Description需要在模型类或序列化器类的字段中以help_text选项定义,如:

    class BookInfo(models.Model):
        ...
        bread = models.IntegerField(default=0, verbose_name='阅读量', help_text='阅读量')
        ...

    class BookReadSerializer(serializers.ModelSerializer):
        class Meta:
            model = BookInfo
            fields = ('bread', )
            extra_kwargs = {
                'bread': {
                    'required': True,
                    'help_text': '阅读量'
                }
            }

    注意 : 基于rese_framework序列化

    接口文档工具 : http://yapi.demo.qunar.com/ yapi

    转载于:https://www.cnblogs.com/HZLS/p/11406520.html

    展开全文
  • 自动生成接口文档 REST framework可以自动帮助我们生成接口文档。 接口文档以网页的方式呈现。 自动接口文档能生成的是继承自APIView及其子类的视图。 安装依赖 REST framewrok生成接口文档需要coreapi库的支持。 ...

    一. 自动生成接口文档

    REST framework可以自动帮助我们生成接口文档。

    接口文档以网页的方式呈现。

    自动接口文档能生成的是继承自APIView及其子类的视图。

    安装依赖

    REST framewrok生成接口文档需要coreapi库的支持。

    pip install coreapi
    

    设置接口文档访问路径

    在总路由中添加接口文档路径。

    文档路由对应的视图配置为rest_framework.documentation.include_docs_urls

    参数title为接口文档网站的标题。

    from rest_framework.documentation import include_docs_urls
    
    urlpatterns = [
        ...
        path('docs/', include_docs_urls(title='站点页面标题'))
    ]
    

    如果报错了下面的错误,说明我们缺少一个依赖,配置一下就行了

    'AutoSchema' object has no attribute 'get_link'

    配置:

    
    REST_FRAMEWORK = {
        ...
        'DEFAULT_SCHEMA_CLASS': "rest_framework.schemas.AutoSchema",
    
    }
    

    文档描述说明的定义位置

    1) 单一方法的视图,可直接使用类视图的文档字符串,如

    class BookListView(generics.ListAPIView):
        """
        get: 返回所有图书信息.
        post: 添加记录
        """
        #注意,这是在类中声明的注释,如果在方法中你声明了其他注释,会覆盖这个注释的
    

    2)包含多个方法的视图,在类视图的文档字符串中,分开方法定义,如

    class BookListCreateView(generics.ListCreateAPIView):
        """
        get:
        返回所有图书信息.
    
        post:
        新建图书.
        """
    

    3)对于视图集ViewSet,仍在类视图的文档字符串中封开定义,但是应使用action名称区分,如

    class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
        """
        list:
        返回图书列表数据
    
        retrieve:
        返回图书详情数据
    
        latest:
        返回最新的图书数据
    
        read:
        修改图书的阅读量
        """
    

    访问接口文档网页

    浏览器访问 127.0.0.1:8000/docs/,即可看到自动生成的接口文档。

    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-q7240NS5-1604824521621)(assets/接口文档页面.png)]

    两点说明:

    1) 视图集ViewSet中的retrieve名称,在接口文档网站中叫做read

    2)参数的Description需要在模型类或序列化器类的字段中以help_text选项定义,如:

    class Student(models.Model):
        ...
        age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄')
        ...
    

    或 注意,如果你多个应用使用同一个序列化器,可能会导致help_text的内容显示有些问题,小事情

    class StudentSerializer(serializers.ModelSerializer):
        class Meta:
            model = Student
            fields = "__all__"
            extra_kwargs = {
                'age': {
                    'required': True,
                    'help_text': '年龄'
                }
            }
    
    展开全文
  • 与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低。与新版的swagger3相比swagger2配置更少,使用更加方便。一、pom文件中引入Swagger3依赖 io....

    前后端分离的项目,接口文档的存在十分重要。与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低。与新版的swagger3相比swagger2配置更少,使用更加方便。

    一、pom文件中引入Swagger3依赖

    io.springfox      springfox-boot-starter      3.0.0

    二、Application上面加入@EnableOpenApi注解

    @EnableOpenApi@SpringBootApplication@MapperScan(basePackages = {"cn.ruiyeclub.dao"})public class Swagger3Application {    public static void main(String[] args) {        SpringApplication.run(Swagger3Application.class, args);    }

    三、Swagger3Config的配置

    @Configurationpublic class Swagger3Config {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.OAS_30)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Swagger3接口文档")                .description("更多请咨询服务开发者Ray。")                .contact(new Contact("Ray。", "http://www.ruiyeclub.cn", "ruiyeclub@foxmail.com"))                .version("1.0")                .build();    }}

    四、Swagger注解的使用说明

    @Api:用在请求的类上,表示对类的说明    tags="说明该类的作用,可以在UI界面上看到的注解"    value="该参数没什么意义,在UI界面上也看到,所以不需要配置"@ApiOperation:用在请求的方法上,说明方法的用途、作用    value="说明方法的用途、作用"    notes="方法的备注说明"@ApiImplicitParams:用在请求的方法上,表示一组参数说明    @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面        name:参数名        value:参数的汉字说明、解释        required:参数是否必须传        paramType:参数放在哪个地方            · header --> 请求参数的获取:@RequestHeader            · query --> 请求参数的获取:@RequestParam            · path(用于restful接口)--> 请求参数的获取:@PathVariable            · body(不常用)            · form(不常用)            dataType:参数类型,默认String,其它值dataType="Integer"               defaultValue:参数的默认值@ApiResponses:用在请求的方法上,表示一组响应    @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息        code:数字,例如400        message:信息,例如"请求参数没填好"        response:抛出异常的类@ApiModel:用于响应类上,表示一个返回响应数据的信息            (这种一般用在post创建的时候,使用@RequestBody这样的场景,            请求参数无法使用@ApiImplicitParam注解进行描述的时候)    @ApiModelProperty:用在属性上,描述响应类的属性

    Controller层的配置:

    @Api(tags = "用户信息管理")@RestController@RequestMapping("userRecord")public class UserRecordController extends ApiController {    /**     * 服务对象     */    @Resource    private UserRecordService userRecordService;    /**     * 分页查询所有数据     * @param page       分页对象     * @param userRecord 查询实体     * @return 所有数据     */    @ApiOperation("分页查询所有数据")    @GetMapping("page")    public R selectAll(Page page, UserRecord userRecord) {        return success(this.userRecordService.page(page, new QueryWrapper<>(userRecord)));    }    /**     * 通过主键查询单条数据     * @param id 主键     * @return 单条数据     */    @ApiOperation("通过主键查询单条数据")    @GetMapping("{id}")    public R selectOne(@PathVariable Serializable id) {        return success(this.userRecordService.getById(id));    }    /**     * 新增数据     * @param userRecord 实体对象     * @return 新增结果     */    @ApiOperation("新增数据")    @PostMapping("insert")    public R insert(@RequestBody UserRecord userRecord) {        return success(this.userRecordService.save(userRecord));    }    /**     * 修改数据     * @param userRecord 实体对象     * @return 修改结果     */    @ApiOperation("修改数据")    @PutMapping("update")    public R update(@RequestBody UserRecord userRecord) {        return success(this.userRecordService.updateById(userRecord));    }    /**     * 删除数据     * @param idList 主键结合     * @return 删除结果     */    @ApiOperation("删除数据")    @DeleteMapping("delete")    public R delete(@RequestParam("idList") List idList) {        return success(this.userRecordService.removeByIds(idList));    }}

    五、Swagger界面效果

    71168c984594f73e1f72949f9600e062.png

    Swagger的访问路径由port/swagger-ui.html改成了port/swagger-ui/ 或port/swagger-ui/index.html,项目演示代码在springboot-swagger

    如果这篇文章对你有帮助的话,记得给我点赞关注走一波,你的鼓励是对我最大的支持!谢谢。

    展开全文
  • 我们在实际项目中,会需要将我们的一些接口的信息返回给前端,便于前后端的交互,在实际使用中,这种自动生成接口文档的模块很多,我主要是用REST framework自动生成接口文档,这个需要用到的是coreapi库的支持,...

      我们在实际项目中,会需要将我们的一些接口的信息返回给前端,便于前后端的交互,在实际使用中,这种自动生成接口文档的模块很多,我主要是用REST framework自动生成接口文档,这个需要用到的是coreapi库的支持,具体使用如下所示

    前言:接口文档是以网页的方式呈现,自动接口文档能生成的是继承了APIView及其子类的视图,继承了其他的则不能自动使用这个生成。

    一、安装依赖

    pip install -i https://pypi.douban.com/simple/ coreapi

    二、设置接口文档访问路径

      在总路由中添加接口文档路径,文档路由对应的视图配置为rest_framework.documentation.include_docs_urls参数title为接口文档网站的标题。

    from rest_framework.documentation import include_docs_urls
    
    urlpatterns = [
        ...
        url('docs/', include_docs_urls(title='站点页面标题'))
    ]

    三、文档描述说明的定义位置

    1.单一方法的视图,可直接使用类视图的文档字符串,如下

    class BookListView(generics.ListAPIView):
        """
        返回所有图书信息.
        """

    2.对于包含了多个方法的视图,在类视图的文档字符串中,分开方法定义,如下

    class BookListCreateView(generics.ListCreateAPIView):
        """
        get:
        返回所有图书信息.
    
        post:
        新建图书.
        """

    3.对于视图集ViewSet,仍在类视图的文档字符串中分开定义,但是应使用action名词区分,如

    class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
        """
        list:
        返回图书列表数据
    
        retrieve:
        返回图书详情数据
    
        latest:
        返回最新的图书数据
    
        read:
        修改图书的阅读量
        """

    在这些都完成以后,我们使用浏览器直接访问127.0.0.1:8000/docs/,即可看到自动生成的接口文档。

    两点说明补充:

    1.对于视图集ViewSet中的retrieve名称,在接口文档网站中叫做read

     2.参数的Description需要在模型类或序列化器类的字段中以help_text选项定义,如:

    class Student(models.Model):
        ...
        age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄')
        ...

    或者

    class StudentSerializer(serializers.ModelSerializer):
        class Meta:
            model = Student
            fields = "__all__"
            extra_kwargs = {
                'age': {
                    'required': True,
                    'help_text': '年龄'
                }
            }

     

    转载于:https://www.cnblogs.com/mcc61/p/11177950.html

    展开全文
  • 自动生成接口文档之JApiDocs教程

    千次阅读 2020-12-09 16:06:20
    所以,自动生成接口文档的工具就出现了。大家最熟悉的应该就是swagger了,我并没有使用过swagger,虽然它比较健壮,稳定。但是由于它的规范很复杂,需要将代码变动的地方也很多。所以我使用了JApiDocs这个工具来为我...
  • Springboot集成Swagger自动生成接口文档为什么使用Swagger来自动生成接口文档1.项目集成Swagger1.1 Maven集成Swagger1.2 Gradle集成Swagger2.开始配置Swagger3.处理入参的实体类User4.处理Controller5.修改...
  • 目录自动生成接口文档1. 安装依赖2. 设置接口文档访问路径3. 文档描述说明的定义位置4. 访问接口文档网页两点说明: 自动生成接口文档 REST framework可以自动帮助我们生成接口文档。 接口文档以网页的方式呈现。 ...
  • 一、开头开发的小伙伴应该会遇到这个问题吧!项目设计阶段写的接口文档,需求的不断的...解决方案一:项目集成 Swagger 插件,前端人员访问 Swagger 生成接口文档,查看和使用接口。解决方案二:项目集成 Swagger...
  • asp.net webapi集成swagger自动生成接口文档(亲测可用)swagger生成html离线接口文档swagger生成html离线接口文档
  • 自动生成接口文档 REST framework可以自动帮助我们生成接口文档。 接口文档以网页的方式呈现。 自动接口文档能生成的是继承自APIView及其子类的视图。 1. 安装依赖 REST framewrok生成接口文档需要coreapi库的支持。...
  • 自动生成接口文档 REST framework可以自动帮助我们生成接口文档。 接口文档以网页的方式呈现。 自动接口文档能生成的是继承自APIView及其子类的视图。 1、安装依赖 REST framewrok生成接口文档需要coreapi库的支持。...
  • DRF 框架总结 - 自动生成接口文档

    千次阅读 2018-12-14 09:52:59
    自动生成接口文档 REST framework可以自动帮助我们生成接口文档。 接口文档以网页的方式呈现。 自动接口文档能生成的是继承自APIView及其子类的视图。 1. 安装依赖 REST framewrok生成接口文档需要coreapi库的支持...
  • 简洁的接口测试,自动生成接口文档,告别繁琐手写接口文档,彻底解放你的双手。 3.自动生成接口文档 在客户端测试好接口之后,接口文档自动生成,快速交付接口文档、实时更新、随时随地分享接口文档。 4.团队协议,...
  • 那么有没有方法能自动生成接口文档来提高前后端的开发效率呢? 自定义动态生成接口文档,手动部署 在对外暴露的接口上添加一套自定义注解。注解可指定接口名称,请求 url,请求方式,请求参数,请求参数类型,返回...
  • Springboot+Swagger自动生成接口文档 pom.xml <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi...
  • 无任何侵入,一键自动生成接口文档,前后端分离开发者的福音
  • 可以为项目自动生成接口文档, 非常的方便快捷 Swashbuckle.AspNetCore 是一个开源项目,用于生成 ASP.NET Core Web API 的 Swagger 文档. 本文采用这个! 一. 利用nuget添加引用 swashbuckle.AspNetCore 二. ...
  • springboot结合swagger自动生成接口文档 前后台分离的开发渐渐已成趋势。那么前后端的沟通就成了问题,包括移动端,web端。如果有一个东西在我们写完代码的时候,自动将接口的所有注释,调用文档提供出来,是不是一...
  • DRF-自动生成接口文档

    2018-11-12 16:37:00
    REST framework可以自动帮助我们生成接口文档。 接口文档以网页的方式呈现。 自动接口文档能生成的是继承自APIView及其子类的视图。 1. 安装依赖 REST framewrok生成接口文档需要coreapi库的支持 pip install...
  • SpringBoot集成Swagger2自动生成接口文档 IBM官网中的Swagger2教程: https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html 1.添加官方依赖 我写文章的时候,Maven存储...
  • SwaggerUi-自动生成接口文档 缺点:代码移入性比较强。 优点:时时同步接口文档,支持在线测试 springBoot集成SwaggerUi 。pom.xml添加引用 <dependency> <groupId>io.springfox</groupId> ...
  • Spring Boot优雅整合Swagger2,自动生成在线文档 日常求赞,感谢老板。 欢迎关注公众号:其实是白羊。干货持续更新中......一、前言现在的很多项目都是前后端分离的,后端提供接口,前端调用接口,在这个过程中一般...
  • DRF - 自动生成接口文档 1. 安装coreapi pip install coreapi 2. 配置 models.py from django.db import models class Book(models.Model): id = models.AutoField(primary_key=True) title = models.CharField...
  • 1 背景 在实际开发中,前后端分离的项目架构已经被越来越多的公司和团体采用,这种架构能够让前端开发人员和后端开发人员在...Swagger2技术能够让开发人员在代码中只是增加少量的注解描述,就能够自动生成接口文档,...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 3,092
精华内容 1,236
关键字:

自动生成接口文档