swagger使用

1、swagger是API工具，Swagger的目的是支撑整个API生命周期的开发，包括设计、文档以及测试和部署

2、swagger所需依赖：
<!– sring mvc依赖 –>
<dependency>
   <groupId>org.springframework</groupId>
   <artifactId>spring-webmvc</artifactId>
   <version>4.2.8.RELEASE</version>
</dependency>

<!– swagger2核心依赖 –>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.6.1</version>
</dependency>

<!– swagger-ui为项目提供api展示及测试的界面 –>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.6.1</version>
</dependency>

3、基本信息配置：--config目录下
/**
 * 基于Swagger生成API文档
 * @author: lijuan
 * @date: 2018/5/17
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.gaoenergy.emos.mov.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("[EMOS 电力市场运行容器]")
                .description("[为交易云平台提供【交易市场运行环境】、【交易市场任务调度】【指令应答库】等功能。]")
                .version("1.0.0-RELEASE")
                .build();
    }
}

基础的配置是对整个API文档的描述以及一些全局性的配置，对所有接口起作用。这里涉及到两个注解：

　　@Configuration是表示这是一个配置类，是JDK自带的注解，前面的文章中也已做过说明。

　　@EnableSwagger2的作用是启用Swagger2相关功能。

4、编写生成API文档的接口：
   @RestController
   @RequestMapping("/user")
   public class UserController {

    @Autowired
    UserService userService;

    @PostMapping("/findOne")
        @ApiOperation(value="查询单个用户",notes="根据id查询单个用户信息")
        @ApiImplicitParam(name="userId",value="userId",required=true,paramType="query")
        public ObjectRestResponse<User> findOne(@RequestParam Integer userId){
            ObjectRestResponse<User> result = new ObjectRestResponse<User>();
            User user = userService.selectById(userId);
            result.data(user);
        return result;
        }
   }

5、启动项目，访问路径：http://localhost:8010/swagger-ui.html

swagger是一款很好用的API工具，能够自动帮我们生成文档确实为我们节省了不少工作，对后续的维护也提供了很大的帮助，Swagger还能根据配置自动为我们生成测试的数据，并且提供对应的HTTP方法，这对我们的自测和联调工作也有不少的帮助。

swagger常用注解以及相关属性说明：

@ApiOperation，整个接口属性配置：

　　　　value：接口说明，展示在接口列表。

　　　　notes：接口详细说明，展示在接口的详情页。

　　　　tags：接口的标签，相同标签的接口会在一个标签页下展示。

　　　　httpMethod：支持的HTTP的方法。

　　@ApiImplicitParams，@ApiImplicitParam的容器，可包含多个@ApiImplicitParam注解

　　@ApiImplicitParam，请求参数属性配置：

　　　　name：参数名称

　　　　value：参数说明

　　　　required：是否必须

　　　　dataType：数据类型　　

　　@ApiResponses，@ApiResponse容器，可以包含多个@ApiResponse注解

　　@ApiResponse，返回结果属性配置：

　　　　code：返回结果的编码。

　　　　message：返回结果的说明。

　　　　response：返回结果对应的类。