SpringBoot整合Swagger2教程

最新推荐文章于 2024-09-04 00:10:29 发布

@ShaneWong

最新推荐文章于 2024-09-04 00:10:29 发布

阅读量216

点赞数 3

本文链接：https://blog.csdn.net/qq_37659485/article/details/117957861

版权

SpringBoot整合Swagger2教程

环境说明

springboot 版本 2.4.4
swagger2 版本 2.9.2

工程准备

创建Springboot工程。这一步不会的可先去HelloWorld，传送门
导入swagger2相关maven依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

配置Swagger2

 我一进门就看见常威在打来福，万物皆对象，万物皆可config
 没得说，先来一个Swagger2Config并创建Docket实例丢给Spring容器

@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .groupName("山河项目组")
                .enable(true) // 是否开启swagger-ui
                .select()
                // basePackage 扫描哪些包
                // withClassAnnotation 基于类的注解扫描
                // withMethodAnnotation 基于方法的注解扫描
                // any 全扫描；none 全部扫描
                .apis(RequestHandlerSelectors.basePackage("tech.yfan.myboot.ctrl"))
                //.apis(RequestHandlerSelectors.withClassAnnotation(ScanSwagger.class))
                //.paths(PathSelectors.ant("/hello/**"))
                .build();
    }
    
    @Bean
    public ApiInfo apiInfo(){
        return new ApiInfo("XXX-Admin接口文档",
                "山河-项目组AA模块接口说明",
                "1.0",
                "http://www.baidu.com",
                new Contact("wangxy", "http://www.baidu.com", "135****465@qq.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());

    }
}

ApiInfo属性含义参见源码ApiInfo.class

源码截图
我是到ApiInfo.class源码抄的静态代码块自己更改的内容，大致就是项目组描述、联系人、联系人邮箱什么的大家改一改网页访问对比以下就知道了

成品图如下
接口示例

@Controller
@RequestMapping("/hello")
@ScanSwagger
@ApiModel("Hello类注释")
public class HelloCtrl {

    /**
     * 此接口访问成功则框架跑的通
     * @return
     */
    @ResponseBody
    @RequestMapping("/hello")
    @ApiOperation("你好方法")
    public String hello(@ApiParam("用户名") String username){
        return "hello";
    }
}

再次成品

这里我给方法（接口）和入参加了注释，便于别人理解（头晕）
下面介绍以下介个注解的用处
注解简述
@Api注解可以用来标记当前Controller的功能。
@ApiOperation注解用来标记一个方法的作用。
@ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
不说了上面这几个注解是我抄一个名叫【江南一点雨】，实在不想码字了
不成蛋的彩蛋
Docket和ApiInfo都是源码点进去复制的静态代码块或构造方法，也不想码字
反人类我
用了这个丝袜哥我并没感觉到有多爽，相反我觉得有点蛋疼，可能我还不太习惯在代码里写接口注释的方式。
这算不算把接口代码和接口文档耦合到一起呢,写完逻辑又在代码里补补注释实在不想这么干，我还是喜欢另起炉灶另找一块地方专门写接口文档。
希望各位老哥解答我的疑惑，衷心的把我吊起来打