学习swagger的使用

目录

什么是swagger？

Swagger 的优势

1.新建一个springboot的项目

2..pom依赖

3.编写一个hello程序

4.配置swagger-->Config

5.测试地址：

配置swagger

让Swagger在特定环境开启，其他环境关闭

配置API文档的分组

---

什么是swagger？

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

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

1.新建一个springboot的项目

2..pom依赖

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

3.编写一个hello程序

4.配置swagger-->Config

@Configuration
@EnableSwagger2    //开启swagger2
public class SwaggerConfig {
}

启动项目发现： springboot无法启动，异常如下：

Failed to start bean 'documentationPluginsBootstrapper';
 nested exception is java.lang.NullPointerException

原因：swagger的版本问题，这是因为Springfox使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。

解决：在application.properties里配置：spring.mvc.pathmatch.matchingstrategy=ANT_PATH_MATCHER。

5.测试地址：

输入：http://localhost:8080/swagger-ui.html

启动后输入测试地址发现404

原因：在swagger3.0中，swagger-ui.html的位置发生了变化

解决方法： 在主启动类上加入@EnableOpenApi注解，加上之后会报找不到该注解，需要导入新依赖

@EnableOpenApi
@SpringBootApplication
public class SwaggerDemoApplication {

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

}

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

重新启动，并输入新地址：http://localhost:8080/swagger-ui/index.html

访问成功

注：如果还是无法访问可以将第2步中的pom依赖注释试一试。

配置swagger

Swagger的bean实例Docket;

在SwaggerConfig类中编写

    //配置了swagger的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo(){
            //作者名，作者网站，邮箱
            Contact contact = new Contact("五十六精研", "https://blog.csdn.net/weixin_46102505", "1845036634.qq.com");
            return new ApiInfo(
                    "我是ljy的swaggerAPI文档",//标题
                    "wsljy的简介",//简介
                    "v1.0",//版本
                    "https://blog.csdn.net/weixin_46102505",//地址
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList());
    
    }

让Swagger在特定环境开启，其他环境关闭

在resources文件夹下创建 application-dev.properties

server.port=8081

创建application-pro.properties

server.port=8082

application.properties中写入

# 环境
spring.profiles.active=dev

//配置了swagger的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要打印的Swagger环境
        Profiles profiles=Profiles.of("dev","test");
        //通过 environment.acceptsProfiles 判断自己是否处于设定的环境中
        boolean flag=environment.acceptsProfiles(profiles);
        System.out.println(flag);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//enable是否启动Swagger，如果为false，那么swagger-ui无法在网页中访问
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage：指定要扫描的包
                //any：扫描全部
                //none：不扫描
                //withClassAnnotation：扫描类上的注解
                //withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.li.swagger.controller"))
                //paths过滤什么路径
                //.paths(PathSelectors.ant("/li/**"))
                .build();
    }

配置API文档的分组

.groupName("张")

如何配置多个分组

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

实体类

package com.li.swagger.pojo;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户类")
public class User {
    //为属性加上get set方法，不管是public还是private都会直接显示
    //public不加get set方法也会显示
    //如果在某个属性是public的情况下添加get set方法会报错
    // 因为法没有办法判断使用set方法给属性赋值，还是直接赋值
    @ApiModelProperty(value = "用户名")
    @JsonProperty("username")
    private String username;

    //private 要显示需要加上@JsonProperty注解
    @ApiModelProperty(value = "密码")
    @JsonProperty("psasword")
    private String psasword;

    //私有的属性swagger没有办法做测试赋值，所以加上get set 方法就可以
    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPsasword() {
        return psasword;
    }

    public void setPsasword(String psasword) {
        this.psasword = psasword;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", psasword='" + psasword + '\'' +
                '}';
    }
}

Controller类

package com.li.swagger.controller;

import com.li.swagger.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 {

    @ApiOperation("hello方法")
    @GetMapping("/hello")
    public String hello(){
        return "hello swagger";
    }

    @ApiOperation("user方法")
    @PostMapping(value = "/user")
    private User user(){
        //只要返回值有实体类那么swagger就会检测的到
        return new User();
    }

    @ApiOperation("hello2方法")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("字符串hello") String hello){
        return hello;
    }

    @ApiOperation("user2方法")
    @PostMapping("/user2")
    public User user2(@ApiParam("用户") User user){
        return user;
    }
}

总结：

我们可以通过swagger给比较难以理解的属性或接口，添加注释信息 接口文档实时更新 可以在线测试。

注意点：在正式发布的时候关闭swagger，出于安全考虑，也能节省内存。