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

小王不头秃

发布于 2024-06-19 16:43:34

850

发布于 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依赖

 <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

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

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

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生成了接口文档，看看成果吧。