欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

Swagger

程序员文章站 2022-07-02 21:07:01
...

1 swagger运行

引用至: https://blog.csdn.net/sanyaoxu_2/article/details/80555328
Swagger
导入相应的依赖

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

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

在Config包底下创建Swagger2

@Configuration
@EnableSwagger2
public class Swagger2 {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 创建该API的基本信息(这些基本信息会展现在文档页面中)
     * 访问地址:http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多请关注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact("sunf")
                .version("1.0")
                .build();
    }

}

.apis(RequestHandlerSelectors.basePackage(“com.controller.HelloController”)): 注意 这里说明的是Controller包的位置, 不是Controller类的全类名

相应的Controller

@Controller
@RequestMapping("/say")
@Api(value = "SayController | 一个用来测试swagger注解的控制器")
public class HelloController {

    @ResponseBody
    @RequestMapping(value ="/getUserName", method= RequestMethod.GET)
    @ApiOperation(value="根据用户编号获取用户姓名", notes="test: 仅1和2有正确返回")
    @ApiImplicitParam(paramType="query", name = "userNumber", value = "用户编号", required = true, dataType = "Integer")
    public String getUserName(@RequestParam Integer userNumber){
        if(userNumber == 1){
            return "张三丰";
        }
        else if(userNumber == 2){
            return "慕容复";
        }
        else{
            return "未知";
        }
    }

    @ResponseBody
    @RequestMapping("/updatePassword")
    @ApiOperation(value="修改用户密码", notes="根据用户id修改密码")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType="query", name = "password", value = "旧密码", required = true, dataType = "String"),
            @ApiImplicitParam(paramType="query", name = "newPassword", value = "新密码", required = true, dataType = "String")
    })
    public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password,
                                 @RequestParam(value="newPassword") String newPassword){
        if(userId <= 0 || userId > 2){
            return "未知的用户";
        }
        if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
            return "密码不能为空";
        }
        if(password.equals(newPassword)){
            return "新旧密码不能相同";
        }
        return "密码修改成功!";
    }

}

完成上述代码添加上,启动Spring Boot程序,访问:

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

@Api:用在类上,说明该类的作用。

@ApiOperation:注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam:用来注解来给方法入参增加说明。
参数:
   ·paramType:指定参数放在哪个地方
      ··header:请求参数放置于Request Header,使用@RequestHeader获取
      ··query:请求参数放置于请求地址,使用@RequestParam获取
      ··path:(用于restful接口)-->请求参数的获取:@PathVariable
      ··body:(不常用)
      ··form(不常用)
   ·name:参数名
   ·dataType:参数类型
   ·required:参数是否必须传(true | false)
   ·value:说明参数的意思
   ·defaultValue:参数的默认值

@ApiResponses:用于表示一组响应

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
      ——code:数字,例如400
      ——message:信息,例如"请求参数异常!"
      ——response:抛出异常的类   

@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)

@ApiModelProperty:描述一个model的属性

Swagger
Swagger
Swagger
Swagger
Swagger

2 每一步分析

首先在config类上标注@Configuration
然后加上@EnableSwagger2
#Swagger

1.1 @Configuration的作用

是一个接口
Swagger
指示一个类声明一个或者多个@Bean 声明的方法并且由Spring容器统一管理
一看到这个注解,我们最浅显的理解就是 这个是取代Spring中的xml配置的。
在类上面标注了@Configuration 指明这是一个Spring的配置文件。
在Spring中我们通过添加@Bean到方法体上。
把它注入到Spring容器中。

1.2 @EnableSwagger2的作用

Swagger

通过Bean把Docket注入到Spring的容器中。

1.3 比较好奇Docket是干嘛的? 为什么要用它?

Docket : 摘要,记事表
进入Docket类中查看源码
Swagger
有一个有参构造器,形参是文件类型DocumentationType
打开DocumentationType类,继承SimplePluginMatadata(简易插件数据)
Swagger
在这个类中,有有参构造器,其中是插件的名字和版本。

1.3.1 API指的是什么?

api 根据英文解释就是 java application interface 应用程序接口
其后有.apiInfo() 调用方法apiInfo 接口信息输入
Swagger
查看一下Swagger
Swagger
在当前类的方法下面我们自己写上apiInfo 信息录入。
Swagger
添加标题,描述,版本等等,最后在建立。

.select() 选择 程序接口建立(当前Docket)
Swagger
.apis(RequestHandlerSelectors.basePackage(“com.controller.HelloController”))
.apis() : 指定所有的接口,告诉明确的路径 请求处理器选择.包名为 “XXX”
.paths(PathSelectors.any())
.paths(): 指定路径
.build(); 然后建立。

1.4 为什么每次在@Configuration中写入Bean都是放回一个实例对象?

上一篇: Swagger

下一篇: swagger使用说明