swagger常用注解

程序员-沐子

已于 2023-07-25 16:11:29 修改

阅读量3k

点赞数 1

CC 4.0 BY-SA版权

文章标签： java spring boot

于 2023-07-25 15:44:53 首次发布

本文链接：https://blog.csdn.net/m0_51666376/article/details/131917856

一、swagger简介

swagger是一款开放源代码软件框架，具有较为完整的生态链，主要用于java后端开发人员设计、调试、和使用RESTful web服务，只需要相关的依赖包和配置类就可以提供高效的使用方式。而postman一般适用于前端人员开发使用。

二、注解(常用的三个注解)

1、@Api

@Api注解主要标注controller类上，表示该类生成的文档，可以指定一些参数（常用参数如下）。

参数①：value 用来指出文档的标题，（例如 value= '教师管理'）

参数②：tags文档的标签（例如tags = '教师接口管理'）

参数③：description用来描述文档（例如tags = '提供教师的增删改查功能'）

@Api(value = "讲师管理" ,tags = "讲师管理功能")
@RestController
@RequestMapping("/eduservice/edu-teacher")
public class TeacherController {

//API接口

}

2、@ApiOperation

@ApiOperation用在请求方法上，说明该方法的作用（常用参数如下）。

参数①：value用来对该方法的说明（例如value = '查询讲师功能'）

参数②：httpMethod接口请求方式（例如httpMethod = 'Post'）

3、@ApiModelProperty

@ApiModelProperty主要用在实体类的属性上，用来指明该属性的含义

参数：value指明属性的含义

    @ApiModelProperty(value = "讲师头像")
    private String avatar;

    @ApiModelProperty(value = "排序")
    private Integer sort;

三、springboot整合swagger

1、添加依赖

要想使用swagger需要先添加swagger依赖

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

2、创建配置类

添加依赖后，创建一个配置类，添加注解@configration（配置类注解），@EnableSwagger2（swagger注解）。

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration    //配置类
@EnableSwagger2    //swagger注解
public class SwaggerConfig {
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("swagger学习API文档")
                .description("本文档描述了课程中心微服务接口定义")
                .version("1.0")
                .contact(new Contact("java", "http://atguigu.com", "1123@qq.com"))  //文档名称，文档发布的网站地址，文档发布者邮箱
                .build();
    }
}

3、添加注解

最后在启动类添加注解，设置包扫描规则。

@SpringBootApplication
@ComponentScan(basePackages = {"swagger所在包的路径"})
public class EduApplication {
    public static void main(String[] args) {
        SpringApplication.run(EduApplication.class,args);
    }
}

4、访问swagger

浏览器中输入网址    http://localhost:8080/swagger-ui.html  (’后端访问地址‘/swagger-ui.html)