Swagger学习-阿里云开发者社区

Swagger简介

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

官网：https://swagger.io/

前后端分离会产生一个问题：全后端集成联调，前端人员和后端人员无法做到“即使协商，尽早解决”，最终导致问题集中爆发

解决方案：

前后端测试接口：postman
后端提供接口，需要实时更新最新的消息及改动。

Swagger

号称世界上1最流行的Api框架
RestFul Api 文档在线自动生成工具（APi文档与APIdi定义同步更新）
直接运行，可以在线测试API接口
支持多种语言：（Java ， PHP）

Spring Boot集成Swagger

1，新建一个SpringBoot项目

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>

3,编写一个Hello工程

@RestController
public class HelloController {
    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

4，配置Swagger

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

5，测试运行：http://localhost:8080/swagger-ui.html 显示如下页面

配置Swagger

Swagger的bean实例Docker

@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    public static final Contact DEFAULT_CONTACT = new Contact(
            "qijian",
            "https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
            "183@qq.com");
    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "Api Documentation  of qijian",
                "作者最帅",
                "1.0",
                "urn:https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>()
        );
    }
}

Swagger配置扫描接口

@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    public static final Contact DEFAULT_CONTACT = new Contact(
            "qijian",
            "https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
            "183@qq.com");
    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
              .enable(true)//是否起用swagger ， 当为false时swagger是不能使用的
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackge:指定扫描的包
                //any()：扫描全部
                //none() : 不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotion:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.qijian.swagger.controller"))
                //paths() 过滤路径
//                .paths(PathSelectors.ant("com1.qijian.demo"))
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "Api Documentation  of qijian",
                "作者最帅",
                "1.0",
                "urn:https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>()
        );
    }
}

当只希望在生产环境中使用，在发布的时候不使用swagger，怎么做？

1，判断是不是生产环境 flag = false

2，注入enable（flag）

    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev" , "test");
        //通过environment.acceptsProfiles判断是否在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//是否起用swagger ， 默认为true ， 当为false时swagger是不能使用的
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackge:指定扫描的包
                //any()：扫描全部
                //none() : 不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotion:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.qijian.swagger.controller"))
                //paths() 过滤路径
//                .paths(PathSelectors.ant("com1.qijian.demo"))
                .build();
    }

配置API的分组

.groupName("A");
• 1

如何配置多个分组，实现多个Docket实例即可

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

项目代码：

目录结构

pom.xml

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

SwaggerConfig （swagger配置类）

package com.qijian.swagger.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.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
/**
 * @author qijian
 * @version 1.0
 * @description
 * @updateRemark
 * @updateUser
 * @createDate 2021/11/4 20:52
 * @updateDate 2021/11/4 20:52
 **/
@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    public static final Contact DEFAULT_CONTACT = new Contact(
            "qijian",
            "https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
            "183@qq.com");
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("C");
    }
    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev" , "test");
        //通过environment.acceptsProfiles判断是否在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//是否起用swagger ， 默认为true ， 当为false时swagger是不能使用的
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackge:指定扫描的包
                //any()：扫描全部
                //none() : 不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotion:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.qijian.swagger.controller"))
                //paths() 过滤路径
//                .paths(PathSelectors.ant("com1.qijian.demo"))
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "Api Documentation  of qijian",
                "作者最帅",
                "1.0",
                "urn:https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>()
        );
    }
}

the code of hellocontroller.java

package com.qijian.swagger.controller;
import com.qijian.swagger.pojo.User;
import io.swagger.annotations.Api;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
 * @author qijian
 * @version 1.0
 * @description
 * @updateRemark
 * @updateUser
 * @createDate 2021/11/4 20:47
 * @updateDate 2021/11/4 20:47
 **/
@RestController
public class HelloController {
    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
    //只要我的接口中存在实体类，返回值中存在实体类，它就会扫描到Swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
    @ApiOperation("Hello控制2")
    @GetMapping(value = "/hello2")
    public String hello(@ApiParam("用户名") String userName){
        return "hello" + userName;
    }
}

the code of user.java

package com.qijian.swagger.pojo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
 * @author qijian
 * @version 1.0
 * @description
 * @updateRemark
 * @updateUser
 * @createDate 2021/11/4 22:56
 * @updateDate 2021/11/4 22:56
 **/
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

启动类：

package com.qijian.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }
}

application配置文件

总结

1，我们可以通过Swagger 给一些比较难以理解的属性或者接口，添加注解信息

2,接口文档实时更新

3，可以在线测试

常用注解：

@Api()用于类；表示标识这个类是swagger的资源 @Api(value="用户controller",tags={"用户操作接口"})

@ApiOperation()用于方法；表示一个http请求的操作

@ApiParam()用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

@ApiModel()用于类表示对类进行说明，用于参数用实体类接收

@ApiModelProperty()用于方法，字段；表示对model属性的说明或者数据操作更改

@ApiIgnore()用于类，方法，方法参数；表示这个方法或者类被忽略

@ApiImplicitParam() 用于方法；表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

文档实时更新

3，可以在线测试

常用注解：

@Api()用于类；表示标识这个类是swagger的资源 @Api(value="用户controller",tags={"用户操作接口"})

@ApiOperation()用于方法；表示一个http请求的操作

@ApiParam()用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

@ApiModel()用于类表示对类进行说明，用于参数用实体类接收

@ApiModelProperty()用于方法，字段；表示对model属性的说明或者数据操作更改

@ApiIgnore()用于类，方法，方法参数；表示这个方法或者类被忽略

@ApiImplicitParam() 用于方法；表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

Swagger学习

Swagger简介

Swagger

Spring Boot集成Swagger

配置Swagger

Swagger配置扫描接口

项目代码：

总结

常用注解：

常用注解：

热门文章

最新文章

相关课程

相关电子书