spring、srpingBoot、springMVC结合swagger

客官°小女子只卖身不卖艺 2022-03-15 09:36 173阅读 0赞

# springBoot、springMVC结合swagger #

在网上看了很多例子，没有一个符合要求

> Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API与接口方法，参数等保存同步，大大减少了接口开发人员的工作量.这个例子是我本地运行正常的，完整demo在文章最后。

## 引用依赖 ##

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

## 配置xml ##

*  **spring容器加载完成以后，再加载swagger即可**

*  **即可以写在spring配置文件中也可以写在springmvc配置文件中，放到这两个文件中最下面即可**

swagger集成spring、springMVC已经完成，启动项目在地址栏中输入[localhost:8080/swagger-ui.html][localhost_8080_swagger-ui.html]即可显示swagger页面  
`注意：` 如果项目根路径配置为“/test”那么访问swagger也需要添加“/test”路径：[localhost:8080/test/swagger-ui.html][localhost_8080_test_swagger-ui.html]

项目中不能包含无任何前缀的访问路径如：GetMapping("")

--------------------

## SpringBoot配置 ##

*  需要引用上述依赖
 *  新建swagger配置类

## 新建配置类 ##

*  新建一个swagger配置类，类名随便起，我这里类名为：Swagger
 *  类的内容为

package com.weixi.restaurant.sell.conf;
    
    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.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /** * @Author: LailaiMonkey * @Description: * @Date: Created in 14:22 2019/2/9 */
    @Configuration
    @EnableSwagger2
    public class Swagger { 
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("指定controller包名"))
                                    .paths(PathSelectors.any())
                                    .build();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2构建RESTful APIs")
                    .title("Spring 中使用Swagger2构建RESTful APIs")
                    .termsOfServiceUrl("https://swagger.io")
                    .contact("swagger启动")
                    .version("1.0")
                    .build();
        }
    
    }

*  访问原理同上所述

## 注解使用 ##

#### Swagger使用的注解及其说明： ####

`@Api：`用在类上，说明该类的作用。

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

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

`@ApiImplicitParam：`用来注解来给方法入参增加说明。

`@ApiResponses：`用于表示一组响应

`@ApiResponse：`用在@ApiResponses中，一般用于表达一个错误的响应信息

code：数字，例如400  
message：信息，例如"请求参数没填好"  
response：抛出异常的类

`@ApiModel：`描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）@ApiModelProperty：描述一个model的属性

注意：@ApiImplicitParam的参数说明：

## 示例 ##

@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){ 
                //方法体内容
        }
    }

[localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[localhost_8080_test_swagger-ui.html]: http://localhost:8080/test/swagger-ui.html