Swagger使用

一 Swagger由来和优势
  现在多数的项目开发中，网站和移动端都需要进行数据交互和对接，这少不了使用REST编写API接口这种场景。 特别是不同开发小组协作时，就更需要以规范和文档作为标准和协作基础。
  良好的文档可以减少沟通成本，达到事半功倍的效果。有时对一些API说明的理解比较模糊，总想着能直接验证一下自己的理解就好了，而不是需要去项目写测试代码来验证自己的想法。
  即API文档应具备直接执行能力，这种能力类似word,wiki等是无法提供。
  SwaggerUI就是这样一种利器，基于html+javascript实现，倾向于在线文档和测试，使用和集成十分简单，能容易地生成不同模块下的API列表， 每个API接口描述和参数、请求方法都
  能定制并直接测试得到直观的响应数据。
  
二 Swagger常用注解使用
        @Api：用在类上，说明该类的作用。
        @ApiOperation：注解来给API增加方法说明。
        @ApiImplicitParams : 用在方法上包含一组参数说明。
        @ApiImplicitParam：用来注解来给方法入参增加说明。
        @ApiResponses：用于表示一组响应
        @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
                code：数字，例如400
                message：信息，例如"请求参数没填好"
                response：抛出异常的类
        @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
        @ApiModelProperty：描述一个model的属性
        
三 Swagger搭建
1 添加依赖

[XML] 纯文本查看 复制代码

?

01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

<dependency>[/size][/font] [font=微软雅黑][size=3]            <groupId>org.springframework.boot</groupId>             <artifactId>spring-boot-starter-web</artifactId>         </dependency>         <dependency>             <groupId>org.mybatis.spring.boot</groupId>             <artifactId>mybatis-spring-boot-starter</artifactId>             <version>2.1.0</version>         </dependency>           <dependency>             <groupId>mysql</groupId>             <artifactId>mysql-connector-java</artifactId>             <scope>runtime</scope>         </dependency>         <dependency>             <groupId>org.springframework.boot</groupId>             <artifactId>spring-boot-starter-test</artifactId>             <scope>test</scope>         </dependency>         <dependency>             <groupId>org.springframework.security</groupId>             <artifactId>spring-security-test</artifactId>             <scope>test</scope>         </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>         <dependency>             <groupId>org.projectlombok</groupId>             <artifactId>lombok</artifactId>             <version>1.18.4</version>         </dependency>         <dependency>             <groupId>com.alibaba</groupId>             <artifactId>druid</artifactId>             <version>1.0.24</version>         </dependency>         <dependency>             <groupId>com.alibaba</groupId>             <artifactId>fastjson</artifactId>             <version>1.2.31</version>         </dependency>

2创建swagger配置类

[Java] 纯文本查看 复制代码

?

01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19

@Configuration     public class SwaggerConfig {         @Bean         public Docket createRestApi() {             return new Docket(DocumentationType.SWAGGER_2)                     .apiInfo(apiInfo())                     .select()                     .apis(RequestHandlerSelectors.basePackage("com.scg.springbootswaggerui.controller")) //添加需生成文档类所在包路径                     .paths(PathSelectors.any())                     .build();         }         private ApiInfo apiInfo() {             return new ApiInfoBuilder()                     .title("swagger-ui 测试")     //文档标题                     .description("swagger-ui 测试")   //文档描述                     .version("1.0")                     .build();         }     }

3定义controller
@RestController
        @Api(value = "LoginController", description = "登陆管理")
        @RequestMapping("/demo/LoginController")
        @Slf4j
        public class LoginController {
                @ApiOperation(value = "获取登录时间接口", notes = "获取登录时间接口")
                @ApiImplicitParam(name = "user", value = "用户", required = true, dataType = "String",paramType="query")        //paramType="query"这个参数很重要参数值不能为path，否则请求参数后台方法接收不到
                @RequestMapping(value = "/login.do", method = { RequestMethod.POST,RequestMethod.GET})
                public Object login(HttpServletRequest request){
                        log.info("打印所有参数："+JSON.toJSONString(request.getParameterMap()));
                        log.info("登陆用户为："+request.getParameter("user"));
                        return new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date());
                }
        }

4启动项目后访问http://localhost:8080/swagger-ui.html

更多免费技术资料可关注：annalin1203