前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >正经人谁写接口文档呀,快来让不正经的swagger帮你写吧

正经人谁写接口文档呀,快来让不正经的swagger帮你写吧

作者头像
小王不头秃
发布2024-06-19 16:43:34
960
发布2024-06-19 16:43:34
举报
文章被收录于专栏:后端/图像融合/机器学习/爬虫

前言

首先要说一下为啥要使用swagger,兄弟们都知道,如今俺们程序员最不喜欢的四件事就是“写文档,写注释,别人不写文档,别人不写注释”

试想一下,当你累的一批,写完了程序并且调试完bug之后,这时前端兄弟找你写一下接口文档,此时你的内心。。。。

这时swagger就派上用场了,来一起看看怎么使用吧。

使用

注解说明

这里先介绍一下swagger部分的注解,基本上这些就够用了。

Controller

注解

可设置属性

使用说明

@Api

tags

标注在controller之上,比较常用;表明该controller的作用,显示在接口文档中

@ApiOperation

value

标注在具体的接口方法上,表明方法的作用,展示在接口文档中

@ApiOperation

notes

标注在具体的接口方法上,表明方法的具体作用,展示在接口文档中

Model

注解

可设置属性

使用说明

@ApiModel

value

标注在class之上,表明实体类的信息,展示在接口文档中

@ApiModelProperty

value

标注在属性之上,表明属性的信息,展示在接口文档中

有了上面这些注解就可以使用swagger制作接口文档了

使用示例

添加maven依赖
代码语言:javascript
复制
 <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
配置swagger
代码语言:javascript
复制
package com.xiaow.swagger.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 1. swagger配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.xiaow.swagger.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("解放后端程序员的神器")
                //文档描述
                .description("和前端交互,不可能")
                //服务条款URL
                //这里填的我的个人博客地址,欢迎各位大佬
                .termsOfServiceUrl("https://xiaow123.gitee.io/hexo_blog")
                //版本号
                .version("1.0.0")
                .build();
    }
}
Controller与Model

Controller

代码语言:javascript
复制
import com.xiaow.swagger.model.TestModel;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@Api(tags = "测试接口")
@RestController
public class TestController {
    @ApiOperation(value="更新用户详细信息", notes="根据url的id来返回对象")
   @GetMapping("/test")
    public TestModel test(@RequestParam(required = true,value = "序号") Integer id){
          return new TestModel()
                  .setEmail("123@xx.com")
                  .setId(id)
                  .setName("xiaow");
   }
}

Model

代码语言:javascript
复制
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;

import java.io.Serializable;

@Data
@ApiModel(value = "测试类")
@Accessors(chain = true)
public class TestModel implements Serializable {
    @ApiModelProperty(value = "序号")
    private Integer id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "邮箱")
    private String email;

}

到现在为止,我们就简单的使用swagger生成了接口文档,看看成果吧。

接口文档

启动项目之后,来到默认swagger接口文档,如下图

按照图中红色箭头依次点击就来到了接口测试

输入参数之后点击execute就实现了接口的调用,如下图

箭头处就是返回的内容。

总结

swagger可以帮我们节省一部分写文档的时间,而且很方便前端程序员进行对接,到现在就完成了swagger的基础使用,是不是蛮简单的,快动手试试吧

本文参与 腾讯云自媒体同步曝光计划,分享自作者个人站点/博客。
原始发表:2024-06-19,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 前言
  • 使用
    • 注解说明
      • 使用示例
        • 添加maven依赖
        • 配置swagger
        • Controller与Model
      • 接口文档
      • 总结
      领券
      问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档