Swagger学习

---

推荐导航

0.系统学习导航传送
>注解介绍
>替换ui界面参考地址

---

一.概述

文档向来在软件开发过程中的每一个阶段都是非常重要的，如果没有文档，那软件的可维护性就会变得很糟，以致于影响可扩展性，最后慢慢的使软件变成一堆乱糟糟的无用的代码。而不同系统之间的接口文档其重要性更显而易见，一般常用的接口文档采用以下形式：

• 口口相传
• 用world或其他文本文件进行保存
• 用wiki编写
  上面这些方式都有各自的缺点，比如不易维护，不易测试接口，接口变更而文档未能同步更新等。但Swagger的出现改变了这些情形，Swagger的文档编写相当于就是在写代码，在更改接口代码的同时就能方便的更新文档，还能方便的进行接口的测试。

二.入门案例

1. 先创建号springboot的web项目 (详细见springboot的入门)

2. 导入swagger的jar

    <!-- swagger2 api文档 -->
        <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>

3. 编写配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
     @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .groupName("RestApi")   //组
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ganyz.springcloudproducer.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("springboot 整合 swagger")//接口文档的标题
                        .description("springboot 整合 swagger test")
                        .version("test 01")
                        .contact(new Contact("name", "url", "email"))    // 开发文档的作者信息
                        .license("license") //license 规范
                        .licenseUrl("licenseUrl")
                        .build());
    }

	// Docket：如果需要分组显示不同文件夹下的controller，则写多个, 否则只需要写上面一个Docket就好了
    @Bean
    public Docket createRestCopyApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .groupName("RestCopyApi")//组
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ganyz.springcloudproducer.controllerCopy"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("springboot 整合 swagger")//接口文档的标题
                        .description("springboot 整合 swagger test")
                        .version("test 01")
                        .contact(new Contact("name", "url", "email"))    // 开发文档的作者信息
                        .license("license") //license 规范
                        .licenseUrl("licenseUrl")
                        .build());
    }
}

4.书写controller

package com.ganyz.springcloudproducer.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
/**
 * @date 2021/5/11
 */
@Api(tags = "用户服务接口swagger")
@Controller
@RequestMapping("swagger2All")
public class SwaggerHelloWorldController {
    @ApiOperation(value = "查询:swagger", notes = "查询swagger的接口")      // value: 请求路径后面的解释;
    @RequestMapping("/swagger")
    @ResponseBody
    public String swagger(){
        System.out.println("swagger=====");
        return "swagger";
    }
}

@Controller
public class HelloWorldController {
    @RequestMapping("/hello")
    @ResponseBody
    public String hello(){
        System.out.println("hello=====");
        return "hello";
    }
}

5. 请求页面地址

地址:http://localhost:10212/swagger-ui

三.注释介绍

• @Api() 用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

tags：说明该类的作用，参数是个数组，可以填多个。
value=“该参数没什么意义，在UI界面上不显示，所以不用配置”
description = “用户基本信息操作”

---

• @ApiOperation()：用于方法，表示一个http请求访问该方法的操作

value=“方法的用途和作用”
notes=“方法的注意事项和备注”
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={“作用1”,“作用2”}
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

---

• @ApiModel()：用于响应实体类上，用于说明实体作用

description=“描述实体的作用”

---

• @ApiModelProperty() 用在属性上，描述实体类的属性

value=“用户名” 描述参数的意义
name=“name” 参数的变量名
required=true 参数是否必选

---

四.swagger替换ui界面

• 关于spring boots中使用swagger-bootstrap-ui 替换默认ui, 导入如下jar

        <!-- swagger2 api文档 -->
        <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>
        <!-- spring boots中使用swagger-bootstrap-ui -->

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.3</version>
        </dependency>

访问地址: http://localhost:10212/doc.html