Swagger学习笔记

最新推荐文章于 2024-02-13 10:56:32 发布

panda_box

最新推荐文章于 2024-02-13 10:56:32 发布

阅读量357

点赞数

文章标签： spring boot swagger2

本文链接：https://blog.csdn.net/qq_23020409/article/details/121564988

版权

学习目标

了解Swagger的作用和概念
了解前后端分离
在Springboot中集成Swagger

一、Swagger简介

主流：前后端分离----Vue+Springboot

后端时代：前端只管理静态页面；html==>后端。模板引擎jsp=>后端是主力

前后端分离时代：

后端：后端控制层、服务层、数据访问层【后端团队】
前端：前端控制层、视图层【前端团队】
- 伪造后端数据，json。已经存在了，不需要后端，前端工程依旧能够跑起来
前后端如何交互？===>API
前后端相对独立，松耦合
前后端可以分别部署在不同的服务器上

产生一个问题：

前后端集成联调时，前后端人员无法做到及时协商，尽早解决问题===>问题爆发！

解决方案：

首先制定一个schema【计划提纲】，实时更新最新API，降低集成风险。
早年使用：制定word计划文档。
前后端分离：
- 前端测试后端数据：postman
- 后端提供接口，需要实时更新最新的消息及改动！

1.Swagger诞生了！

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

2.Swagger官网：

API Documentation & Design Tools for Teams | Swagger

3.在项目中使用Swagger

需要springfox:

swagger2
ui

二、SpringBoot集成Swagger

1.新建SpringBoot-web项目

2.导入相关依赖

Maven官网：https://mvnrepository.com/

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>

Swagger3.0.0不需要依赖那么多包：

pom.xml

<!--https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

3.编写一个Hello工程

4.配置Swagger

===>Config

@Configuration
/** @EnableSwagger2 //开启Swagger2 */
/** SpringBoot2.6.0集成Swagger3.0.0 已经不用@EnableSwagger2了,
用@EnableWebMvc */
@EnableWebMvc  //Swagger3.0.0配置
public class SwaggerConfig {
    
}

启动类添加@EnableOpenApi注解

@SpringBootApplication
@EnableOpenApi   //Swagger3.0.0配置
public class SwaggerDemoApplication {

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

}

5.测试运行

启动程序，访问 http://localhost:8080/swagger-ui/index.html

三、配置Swagger

Swagger的bean实例：Docket

1.写配置

@Configuration
@EnableWebMvc
public class SwaggerConfig {

    //配置了Swagger的Docket实例bean
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger信息apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("Panda", "https://blog.kuangstudy.com/", "iluopan@163.com");

        return new ApiInfo(
               "Panda Swagger Api", 
               "Panda的Swagger测试文档-狂神学子",
               "1.0",
               "https://blog.kuangstudy.com/",
                contact,
               "Apache 2.0",
               "http://www.apache.org/licenses/LICENSE-2.0",
               new ArrayList()
       );
    }
}

2.访问

http://localhost:8080/swagger-ui/index.html#/

四、配置扫描接口

1.Docket.select().build();

//配置了Swagger的Docket实例bean
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors配置要扫描接口的方式
            //basePackage()指定包扫描
            //any()扫描全部
            //none()不扫描
            //withClassAnnotation()扫描类上的注解，RestController.class
            //withMethodAnnotation()扫描方法上的注解，GetMapping.class
            .apis(RequestHandlerSelectors.basePackage("com.panda.swagger.controller"))
            /** .paths(PathSelectors.ant("/panda/**")) //过滤 */
            .build();
}

2.Docket.enable();

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

        //设置要显示Swagger的环境
        Profiles profiles=Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断自身是否处于设定的环境中
        boolean isInEnvironment=environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(isInEnvironment) //是否启用Swagger
                .select()
            .apis(RequestHandlerSelectors.basePackage("com.panda.swagger.controller"))
                .build();
    }

访问： http://localhost:8081/swagger-ui/index.html#/

五、分组

1.Docket.groupName();

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

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

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

六、实体类配置

1.接口返回值存在实体类自动扫描到Model

@PostMapping(value = "/user")
public User user(){
    return new User();
}

2.在实体类上可以加注解

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String userName;
    @ApiModelProperty("密码")
    public String password;
}

3.在Controller层方法上可以加注释

@ApiOperation("用户接口")
@PostMapping(value = "/user")
public User user() {
	return new User();
}

@ApiOperation("hello2")
@GetMapping(value = "/hello2")
public String hello2(@ApiParam("用户名") String userName) {
            return "hello2"+userName;
}