Swagger简单应用

Code_Xiaotian

已于 2022-03-04 21:45:22 修改

阅读量968

点赞数 1

分类专栏：后端框架文章标签： java postman spring boot

于 2022-03-04 21:40:57 首次发布

本文链接：https://blog.youkuaiyun.com/m0_46313726/article/details/123285695

版权

后端框架专栏收录该内容

10 篇文章

订阅专栏

3、SpringBoot集成Swagger

1、前后端分离

前后端分，分离是目前一种非常流行的开发模式，它使项目的分工更加明确：

后端：后端控制层，服务层，数据访问层；负责处理、存储工程
前端：前端控制层，视图层；负责显示数据

前端和后端是通过接口进行数据交换

1.2、为什么要进行前后端分离

前后端可以专注于各自擅长的领域
避免后端写前端代码
前端配置后端代码运行环境
避免前后端发生矛盾
前后端相对独立，松耦合
前后端甚至可以部署在不同的服务器上

1.3、前后端分离存在的问题

前后端集成联调，前端人员和后端人员无法做到“及时协商，尽早解决”，最终导致问题集中爆发
当接口改变时，非常麻烦

解决方案：

首先制定schema【计划的提纲】，实时更新最新API，降低集成的风险
前后端分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更新最新的消息及改动

2、Swagger

最流行的Api框架
RestFul Api文档在线自动生成工具=>
直接运行，可以直接在线测试Api接口
支持多种语言：java、php...

官网：API Documentation & Design Tools for Teams | Swagger

总项目结构：

2.1、在项目中使用Swagger

在项目中使用Swagger需要springbox

swagger2
ui

3、SpringBoot集成Swagger

新建SpringBoot Web项目

导入相关依赖

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

配置Swagger==>Config

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

编写hello工程
测试运行：http://localhost:8080/swagger-ui.html

4、配置Swagger信息

@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("天赐", "abcd...", "2312103658@qq.com");
        return new ApiInfo(
            "Swagger-Demo",
            "Swagger-test",
            "1.0",
            "urn:tos",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
    }
}

5、Swagger配置扫描接口

Docket.select()方法

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        //RequestHandlerSelectors，配置扫描接口方式
        //basePackage:指定要扫描的包 一般是这个
        //any:扫描全部
        //none:不扫描
        //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
        //RequestHandlerSelectors.withClassAnnotation(controller.class)
        //withMethodAnnotation：扫描方法上的注解
        //RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class)
        .apis(RequestHandlerSelectors.basePackage("com.wen.swaggerdemo.controller"))
        //path():过滤xx路径
        //ant:过滤该路径下的
        //any:过滤所有
        //none:不过滤
        //regex:正则
        //.paths(PathSelectors.ant("/wen/**"))
        .build();//build前面select的方法：apis(扫描接口)、paths(过滤接口)
}

5.1、apis

apis中有RequestHandlerSelectors，点击进入看源码：

RequestHandlerSelectors，配置扫描接口方式
basePackage:指定要扫描的包一般是这个
any:扫描全部
none:不扫描
withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象 RequestHandlerSelectors.withClassAnnotation(controller.class)
withMethodAnnotation：扫描方法上的注解 RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class)

5.2、paths

paths中有PathSelectors，点击进入查看源码：

path():过滤xx路径
ant:过滤该路径下的
any:过滤所有
none:不过滤
regex:正则
例：.paths(PathSelectors.ant("/wen/**"))

6、配置是否启动Swagger

Docket.enable()方法

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        //enable:是否启用Swagger，如果为False，则Swagger不能再浏览器中访问
        .enable(false)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.wen.swaggerdemo.controller"))
        //.paths(PathSelectors.ant("/wen/**"))
        .build();//build前面的方法：apis、paths、build
}

点击查看源码可知：

传入布尔值：如果为False，则Swagger不能再浏览器中访问

6.1、enable应用

只想Swagger在生产环境中使用，但在发布时不使用

判断是不是生产环境 flag=false
注入enable(flag)

添加两个环境application-dev.properties(项目环境)、application-pro.properties(发布环境)

2.在两个环境中设置各自的端口号，然后在application.properties中激活dev环境

application.properties：
spring.profiles.active=dev

application-dev.properties：
server.port=8081

application-pro.properties：
server.port=8082：

3.因为是在enable中通过布尔值来判断是否是当前环境，所以在Docket中添加Environment，通过Environment的acceptsProfiles方法来实现。

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

    //获取项目的环境：dev
    //设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev");
    //通过environment.acceptsProfiles(profiles)判断是否处在设定的环境中
    boolean flag = environment.acceptsProfiles(profiles);

    ...

点击acceptsProfiles可以看到有两个方法，但第一个方法已过期了，所以用第二个方法，第二个方法内有一个Profiles参数，所以得创建一个Profiles，Profiles便是设置要显示的环境。

4.启动项目可以看到，当端口号为dev：8081时，可以进入Swagger界面，但是为pro：8082时却进不了。

7、配置Api文档的分组

通过Docket内的.groupName()方法来设置文档的名字

.groupName("小天")

7.1、配置多个分组

可以通过创建多个Docket实例来创建多个分组，这样就可以实现每个人负责各自的组

有助于协同开发。

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("小小");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("小三");
}
@Bean
public Docket docket4(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("老四");
}

7.2、实体类配置(Model)

@ApiModel("")：实体类注释
@ApiModelProperty("")：字段注释

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

@ApiOperation("")：controller方法注释
@ApiParam("")：方法参数注释

//只要接口中，返回值中存在实体类，就会被扫描到swagger中
@PostMapping("/user")
public User user(){
    return new User();
}

@ApiOperation("hello2控制类")
@PostMapping("/hello2")
public String user2(@ApiParam("用户名") String username){
    return "hello"+username;
}