Swagger 学习心得

最新推荐文章于 2024-08-30 08:40:44 发布

Paracosm

最新推荐文章于 2024-08-30 08:40:44 发布

阅读量237

点赞数

文章标签： swagger2

本文链接：https://blog.csdn.net/Paracosm/article/details/109785806

版权

Swagger

前后端分离

Vue+SpringBoot

后端时代:前端只用管理静态页面; html==>后端. 模板引擎JSP=>后端是主力

前后端分离时代:

后端:控制层,服务层,数据访问层
前端:控制层,视图层
前后端如何交互?===>API
前后端相对独立,松耦合;
前后端甚至可以部署在不同的服务器上.

产生一个问题

前后端集成联调,前端人员和后端人员无法做到"及时协商,今早解决",最终导致问题集中爆发

解决方案:

首先指定schema[计划],实时更新最新的API,降低集成的风险.
早些年:制订word计划文档.
前后端分离:
- 前端测试后端接口:postman
- 后端提供接口,需要实时更新最新的消息及改动.

Swagger

号称世界上最流行的Api框架
RestFul Api 文档在线自动生成工具=>Api文档与Api定义同步更新.
直接运行,可以在线测试Api接口
支持多种语言

在项目中使用Swagger (需要SpringFox)

swagger2
ui

SpringBoot集成Swagger

1.导入依赖

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

    
    #注意,这里3.0.0版本的用以前的url打不开ui端口,记得换成2.9,2!

2.编写一个Hello工程

3.配置Swagger ==>Config

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

}

4.运行测试

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

配置Swagger

Swagger的bean实例 Docket:

@Configuration
@EnableSwagger2 //开启Swagger2
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("芜湖", "http://www.baidu.com/", "704965520@qq.com");

        return new ApiInfo("nmsl的Swagger Api文档",
                "呜呼呜呼",
                "1.0",
                "http://www.baidu.com/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

Swagger配置扫描接口

Docket.select()

public class SwaggerConfig {

    //配置Swagger的docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式    basePackage 指定要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.nmsl.controller"))
                //path() 过滤路径
                .build();
    }


    //配置了Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("芜湖", "http://www.baidu.com/", "704965520@qq.com");

        return new ApiInfo("nmsl的Swagger Api文档",
                "呜呼呜呼",
                "1.0",
                "http://www.baidu.com/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

配置是否启动Swagger

Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(true)

我只希望我的Swagger在生产环境中使用,在发布的时候不使用.

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

注入enable(flase)

 @Profile("dev")
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev","test");
//获取项目环境,通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);

配置API文档的分组

多个Docket实例

实体类配置

只要接口中，返回值中存在实体类它就会被扫描到Swagger中

@ApiOperation("Hello控制类")   //给controller方法加注释
//只要接口中，返回值中存在实体类它就会被扫描到Swagger中
@GetMapping(value = "/user")
public User user(){
    return new User();
}

@GetMapping(value = "/user2")
public String user2(@ApiParam("用户名") String username){  //给用户名加注释
    return "hello"+username;
}

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类注释")    //用户实体类的注释
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

}