Swagger 补习

最新推荐文章于 2025-02-20 15:45:48 发布

paleatta

最新推荐文章于 2025-02-20 15:45:48 发布

阅读量181

点赞数

文章标签： swagger2

本文链接：https://blog.youkuaiyun.com/paleatta/article/details/111873873

版权

本文介绍了如何在Springboot项目中使用Swagger2，包括Swagger的基本概念、如何输出HelloWorld、自定义Swagger信息、设置扫描范围和Swagger-UI开关、接口分组及注释的使用，旨在解决前后端交互问题。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

狂神说Swagger
学完Mybatis-Plus才发现没学过这个，补习一下吧，感觉也挺简单的。

随看随记

Swagger简介

Swagger官网
其作用是提供API，解决前后端的交互不及时的问题。
需要在项目中引入Swagger2 和Swaggerui。

Springboot继承Swagger 输出HelloWorld

访问时要访问:localhost:8080/swagger-ui.html

@Configuration
@EnableSwagger2
public class swaggerConfig {
}

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

自定义Swagger信息

其中比较有用的就只有ApiInfo的第一个参数和第二个参数
分别代表API文档的名称和Api文档的简介

@Configuration
@EnableSwagger2
public class swaggerConfig {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("paleatta","http://localhost:8080/","123456789@qq.com");

        return new ApiInfo(
                "Swagger练习API",
                "技术宅拯救世界",
                "1.0bate",
                "http://localhost:8080/"",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

设置扫描范围和swagger-ui开关

更改Docket environment参数是用来判断生产环境用的，这里配置的是只在dev下才启用swagger

@Bean
public Docket docket(Environment environment) {
    Profiles profiles = Profiles.of("dev");
    boolean flag = environment.acceptsProfiles(profiles);
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //是否启用swagger
            //通过在何种环境下来决定是否启用swagger
            .enable(flag)
            .select()
            //设置要扫描所有的包
            //.apis(RequestHandlerSelectors.any())
            //所有的包都不扫描
            //.apis(RequestHandlerSelectors.none())
            //扫描类注解为RestController的类
            //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            //扫描方法注解为RequestMapping的方法
            //.apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
            //扫描指定包 常用
			.apis(RequestHandlerSelectors.basePackage("com.paleatta.swagger.controller"))
            //过滤器，只扫描接口的第一路径为paleatta的路径
            .paths(PathSelectors.ant("/paleatta/**"))
            .build()
            ;
}

分组

分组只需要在后面加上.apiInfo(apiInfo())前.groupName(“paleatta”)
表示这些API是由paleatta所写的
所以最完整的Docket 应该如下

@Bean
public Docket docket(Environment environment) {
    Profiles profiles = Profiles.of("dev");
    boolean flag = environment.acceptsProfiles(profiles);
    return new Docket(DocumentationType.SWAGGER_2)
    		//表明分组
    		.groupName("paleatta")
            .apiInfo(apiInfo())
            //是否启用swagger
            //通过在何种环境下来决定是否启用swagger
            .enable(flag)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.paleatta.swagger.controller"))
            //过滤器，只扫描接口的第一路径为paleatta的路径
            .paths(PathSelectors.ant("/paleatta/**"))
            .build()
            ;
}
    private ApiInfo apiInfo(){
        Contact contact = new Contact(
						        "paleatta",
						        "http://localhost:8080/",
						        "123456789@qq.com");

        return new ApiInfo(
                "Swagger练习API",
                "技术宅拯救世界",
                "1.0bate",
                "http://localhost:8080/"",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

接口注释

@ApiModel表示对象的描述 @ApiModelProperty表示对象的属性的描述
主要用于实体类

 @ApiModel(value="User对象", description="")
public class User implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "主键ID")
    private Long id;

    @ApiModelProperty(value = "姓名")
    private String name;

    @ApiModelProperty(value = "年龄")
    private Integer age;

    @ApiModelProperty(value = "邮箱")
    private String email;

@ApiOperation("")表示对后端方法的描述只能放在方法上
@ApiParam("") 表示对方法的变量加上注释
当方法中有对象时，会自动监测该对象

@RestController
public class HelloController {
    @ApiOperation("helloworld")
    @RequestMapping("/he")
    public String hello(){
        return "hello";
    }
}

    @ApiOperation("输入User对象")
    @PostMapping("/hello1")
    public User hello1(@ApiParam("用户类")User user) {
        return user;
    }