Swagger食用方法详解

2023-11-17 18:03:31

你们项目中有用到Swagger吗？你真的会用这个框架吗？哈哈，都说用了Swagger的都不用写文档了，但是打开项目的Swagger地址看看，惨不忍睹啊！都是些什么东西啊，完全看不到任何有用的信息，东西没用好就是这样的结果！

概念

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

作用

  • 1.接口的文档在线自动生成
  • 2.功能测试

导入依赖

<!-- 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>

之前我们说springboot用啥就引入对应的starter就好了，那么这里你也可以引入对应的starter，但是这个是默认UI的没法改！

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.0.RELEASE</version>
</dependency>

注：Springfox是践行OAS的一个项目，它将Swagger融合进流行的Spring框架，根据OpenAPI规范，帮助开发者自动生成API文档

开启Swagger及其配置

@Configuration
public class SwaggerConfig {

    // 注册bean Docket 
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).; 
    }
}

@SpringBootApplication
@EnableSwagger2// 使Swagger生效，默认是不开启!
public class SpringStudyApplication {

	public static void main(String[] args) {
		SpringApplication.run(SpringStudyApplication.class, args);
	}
}

启动测试

默认地址：http://localhost:8080/swagger-ui.html
Swagger食用方法详解
可以看到这里有一个basic-error-controller 和我们自己定义的一个controller

点开我们自己定义的一个controller看下：
Swagger食用方法详解
可以看到一个接口各种类型的请求，这是为什么呢？是因为我用到是@RequestMapping注解，且没有指定请求类型。
我们改成@RequestMapping(value="/getDepartments",method= RequestMethod.GET)或@GetMapping(value="/getDepartments")再看：
Swagger食用方法详解
现在就只剩一个方式的请求了，所以写接口请求方式这里一定要定义清楚，别偷懒，习惯真的很重要！

但是很多人用就仅仅用到这一步了，打开看看别说前端看不懂时间长了自己写的都认不得了！

再配置及规范

配置docket

可以点进源码看看，阅读源码的方法：看其实现和继承->看其构造方法->看其重写方法->看其其他方法实现

这里就不再赘述，直接看其构造方法，配置Swagger的参数！

package com.springstudy.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.PathSelectors;
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 java.util.ArrayList;

@Configuration
public class SwaggerConfig {

    // 注册bean Docket
    @Bean
    public Docket docket(Environment env){
        // 设置要显示swagger的环境 在application.properties 中配置spring.profiles.active=dev
        // spring 配置的优先级是properties>yaml文件的
	// 所以我一般保留一个properties来配置最高权限的配置
        // 而application.yaml用来配置数据库连接池等通用配置
        Profiles pro = Profiles.of("dev","test");
        // 判断是否是对应的环境
        boolean enable = env.acceptsProfiles(pro);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // 配置文档信息!
                .enable(enable) // 如果是false就无法在浏览器中访问，可以配置
                .select()
        	//配置哪些目录下的被扫描          
		.apis(RequestHandlerSelectors.basePackage("com.springstudy.controller"))
                .paths(PathSelectors.ant("/test/**")) //配置只扫描/test开头的请求
                .build();
    }

    // 配置文档信息 apiInfo
    private ApiInfo apiInfo(){
    Contact contact = new Contact("城南花已开","http://123.57.82.136:8080/","1156947957@qq.com");
    //public static final Contact DEFAULT_CONTACT = new Contact("name", "url", "email");
    //DEFAULT = new ApiInfo(
        // "Api Documentation",
        // "Api Documentation",
        // "1.0", "urn:tos",
        // DEFAULT_CONTACT,
        // "Apache 2.0",
        // "http://www.apache.org/licenses/LICENSE-2.0",
        // new ArrayList());
    return new ApiInfo(
    "SpringBoot-study 接口文档信息",
            "所有的测试请求地址",
            "v1.0",
            "http://123.57.82.136:8080/", //服务地址，可以配置公司官网
             contact,//组织连接
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
    }
}

补充说明：
Swagger食用方法详解

any() // 扫描所有，项目的所有接口都会被扫描的
none() // 不扫描接口
basePackage() // 根据包路径扫描
withMethodAnnotation(GetMapping.class) // 通过方法注解扫描! 比如 GetMapping.class 
withClassAnnotation(Controller.class) // 通过类上的注解扫描! 比如 Controller.class

Swagger食用方法详解

ant() // 指定扫描路径
any() // 扫描整个项目
none() // 都不扫描
regex() // 根据正则匹配扫描

新增“/test/hello"路径下接口我们来看下效果：
Swagger食用方法详解

分组

return new Docket(DocumentationType.SWAGGER_2)
        .groupName("test")//新增分组配置
        // ...其他代码省略
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

看下分组效果：
Swagger食用方法详解

swagger注解

实体：

package com.springstudy.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel("部门实体")
public class Department {

    @ApiModelProperty("部门id")
    private Integer id;

    @ApiModelProperty("部门名称")
    private String departmentName;
}

controller :

package com.springstudy.controller;

import com.springstudy.dao.DepartmentMapper;
import com.springstudy.entity.Department;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/department")
@Api(tags={"部门接口"})
public class DepartmentController {

    @Autowired
    DepartmentMapper departmentMapper;
 
    @ApiOperation("通过id获取部门数据")
    @GetMapping("/getDepartment/{id}")
    public Department getDepartment(@ApiParam("部门id") @PathVariable("id") Integer id){
        return departmentMapper.getDepartment(id);
    }
}

基本写到这样就可以来哈，太多了也显得乱！简洁明了即可

ui选型

  • 1.默认的 http://localhost:8080/swagger-ui.html 
<!-- 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>
  • 2.BootStrap-ui http://localhost:8080/doc.html 
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
<dependency>
    <groupId>com.github.xiaoymin</groupId> 
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

Swagger食用方法详解
个人最喜欢这款，其他的自己去尝试，或者可以研究下底层api接口自己写个皮肤出来，然后开源出来嘛！

  • 3.Layui的框架 http://localhost:8080/docs.html 
<!-- https://mvnrepository.com/artifact/com.github.caspar-chen/swagger-ui-layer -->
<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 
<dependency> 
    <groupId>com.zyplayer</groupId> 
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

本来没想写swagger的，但是最近改别个系统遗留下的bug，前台传参巨复杂,后台代码写的及其没有层次感，关键地方一句注释没有，真是要了老命，想着看看swagger-ui 上接口及返回值有没有说明，发现啥也没有。可真是骂人的心都有了，怎么一点规范都没有呢？！这东西也不是有多难，但是吧一直觉得用一个东西，如果不能用好还不如不用！

上一篇：spring boot整合swagger详解


下一篇：3、集成springfox-swagger 3.0.0 + 集成knife4j