Swagger组件学习 - 20181201

Swagger学习笔记

一.引言

• Swagger是一个功能强大的API框架，用于生成、描述、调用、测试和可视化restful风格的web服务

• 什么是OAS?
  OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。目前V3.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。即swagger2.0是基于 The Apache License, Version 2.0许可的OAS3.0实现。

• 什么是Swaggger？
  Swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。

• 简而言之：
  Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。
  Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。
  Swagger 是一种通用的，和编程语言无关的 API 描述规范
  前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。
  官网：https://swagger.io/

二.Swagger 、Swagger UI、 Springfox简介，三者之间的联系

• SwaggerUI
  允许用户使用Swagger编辑器描述OAS 3.0 API，并使用SwaggerUI可视化并自动生成OAS3.0中定义的文档
• Springfox
  用Spring构建自动的 JSON API文档工具；暂时只支持Swqgger2.0.
  简而言之，就是基于spring框架的，java语言自动的一个OAS文档生成工具
• 关系图例
  

三.Springboot 集成Swagger

1. 创建springboot工程
2. 导入依赖

 <!--swagger2 依赖-->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.7.0</version>
   </dependency>
   
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.7.0</version>
   </dependency>

3. 准备配置类

/**
 * springboot 和 Swagger整合
 */
@Configuration
@EnableSwagger2
public class SpringFoxConfig {//SwaggerConfig同SpringFoxConfig
    @Bean
    public Docket apiDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // rest controller package
                .apis(RequestHandlerSelectors.basePackage("com.baizhi.controller"))     //指定扫描的包会生成文档
                .paths(PathSelectors.any())   //选择所有路径 也可使用/xx/**形式
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot 和 Swagger整合")
                .description("我的swagger2入门学习")
                .termsOfServiceUrl("http://www.test.cn")
                .contact("my test")
                .version("1.0")
                .build();
    }
}

4. 路径访问 swagger api 的默认地址是/v2/api-docs
   示例：http://localhost:9090/自定项目名/v2/api-docs

5. 响应结果 json形式

{
	"swagger":"2.0",
	"info":{
		"description":"我的swagger2入门学习",
		"version":"1.0",
		"title":"springboot 和 Swagger整合"
		,"termsOfService":"http://www.test.cn",
		"contact":{
			"name":"my test"
			}
		},
	"host":"localhost:9090",
	"basePath":"/sf"
}

四.Swagger文档的生成注解（起别名）

Swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiClass
@ApiError
@ApiErrors
@ApiImplicitParam：一个请求参数
@ApiImplicitParams多个请求参数

五.Restful风格controller开发

@Api(value = "swagger controller",tags = "swagger操作接口")
@RestController
@RequestMapping("/rest")
public class RestController {

    @ApiOperation(value = "根据用户名 获取欢迎语",notes = "注意事项")
    @GetMapping("/helloello")
    public String sayHello(@ApiParam(name="name",value = "用户名",required = true)
                           @RequestParam(required = true)
                                   String name){
        return "Hello: "+name;
    }

    //@ApiIgnore
    @ApiOperation(value = "新增用户信息")
    @PostMapping("/add")
    public String addUser(@RequestBody @ApiParam(name="user",value="用户对象",required =
            true) User user){
        System.out.println(user);
        return "OK";
    }
    @ApiOperation(value = "根据年龄和姓名查询用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name="userAge",value = "用户年龄",required =
                    true,dataTypeClass = Integer.class,paramType = "query"),
            @ApiImplicitParam(name="name",value="用户姓名",dataType = "string",paramType
                    = "query")
    })
    @GetMapping("/select")
    @ApiResponses({
            @ApiResponse(code = 404,message = "没有找到资源"),
            @ApiResponse(code = 401,message = "权限不够")
    })
    public  String selectUser(@RequestParam("userAge") Integer age,String name){
        return age + " | "+name;
    }
}

其他资料

• 5分钟了解swagger https://blog.csdn.net/i6448038/article/details/77622977
• Swagger 入门和实战 https://blog.csdn.net/lamp_yang_3533/article/details/80114083
• SpringMVC集成springfox-swagger2自动生成接口文档 https://www.cnblogs.com/zhaojiankai/p/8318359.html
• 特别好用的swagger ui 封装 https://www.cnblogs.com/myhappylife/p/9403563.html#autoid-0-0-0
• b站视频学习 https://search.bilibili.com/all?keyword=Swagger&from_source=banner_search
• Swagger – RESTFUL接口文档在线自动生成以及功能测试 英文文档汉化
  http://blog.fudenglong.site/2017/11/26/Swagger-RESTFUL接口文档在线自动生成以及功能测试/?utm_source=wechat_session&utm_medium=social&utm_oi=722241086042443776