Swagger

Swagger简介

前言

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单

使用介绍 什么是 Swagger?

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。 浏览 Swagger-Spec 去了解更多关于Swagger 项目的信息，包括附加的支持其他语言的库。

Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用,属性tags（说明该类的作用，可以在UI界面上看到的注解）表示分类

@ApiOperation：描述一个类的一个方法，或者说一个接口,value就是说明作用，notes详细说明

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数 ，标注在实体类上

@ApiModelProperty：用在实体属性上，标记属性名称和说明内容，name代表属性名称，value表示属性内容，hidden是否隐藏，默认是false。

@ApiResponses：用于请求的方法上，表示一组响应

@ApiResponse用在@ApiResponses注解中，一般用于表达一个错误的响应信息

​ code:响应码(数值，如400)

​ message:信息，如：“请求参数没填好”

​ response:抛出异常的类

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParams：多个请求参数

用在方法上，表示一组参数说明

@ApiImplicitParam用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

​ name:参数名，

​ value:参数的中文说明、解释，

​ required:是否必填，

​ dataType:参数类型，默认string，其他值dataType="Integer",

​ defaultValue : 参数的默认值，

​ paramType:参数放在哪个地方

​ header --> 请求参数的获取 ：@RequestHeader

​ query --> 请求参数的获取：@RequestParam

​ path --> (用于restful接口) --> 请求参数的获取 ：@PathVariable

​ body (不常用)

​ form (不常用)    

Spring Boot集成Swagger

Spring Boot的版本需要2.5.7以下的

导入依赖

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

浏览器输入：http://localhost:8080/swagger-ui.html 访问即可

SwaggerConfig

package com.yuan.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;

@EnableSwagger2// 开启Swagger2的自动配置
@Configuration //配置类
public class SwaggerConfig {

    //配置了Swaagger的Docket的bean实例
    @Bean//配置docket以配置Swagger具体参数
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles=Profiles.of("prod","test");
        //通过environment.acceptsProfiles判断是否处于在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                //.enable(flag)//enab1e是否启动Swagger，如果为Fa7se，则Swagger不能再浏览器中
                .groupName("yuan")
                .select()
                //RequestHandlerselectors,配置要扫描接口的方式
                // basePackage:指定要扫描的包
                //any ():扫描全部
                //none():不扫描
                //withclassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                // withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.yuan.controller"))
                //设置什么路径
                //.paths(PathSelectors.ant("/yuan/**"))
                .build();
    }
    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
    //分组
    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A组");
    }
    @Bean
   public Docket docket2() {
       return new Docket(DocumentationType.SWAGGER_2).groupName("B组");
   }
}

HelloController

package com.yuan.controller;
import com.yuan.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello";
    }
    @PostMapping("/user")
    public User user() {
        return new User();
    }
    @ApiOperation("用户Controller跳转")
    @GetMapping("/user2")
    public String user2(@ApiParam("用户名") String username) {
        return "user"+username;
    }
}

User

package com.yuan.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

//@Api("注释信息")
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

application.properties

spring.profiles.active=prod

application-dev.properties

# 开发环境
server.port=8081

application-prod.properties

# 生产环境
server.port=8082

拓展：Swagger皮肤

1、默认的 访问 http://localhost:8080/swagger-ui.html

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

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

3、Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

4、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>