Swagger入门

目录

1.为什么使用Swagger2

2.Swagger2 的优点

3.快速上手 SpringBoot 集成 Swagger2

        3.1 导入依赖

        3.2 编写配置文件

        3.3 控制层

        3.4 测试运行 http://localhost:8080/swagger-ui.html        

4. Swagger2注解详解

         4.1 @Api ：请求类的说明

        4.2 @ApiOperation：方法的说明

         4.3 @ApiImplicitParams、@ApiImplicitParam：方法参数的说明

        4.4 @ApiResponses、@ApiResponse：方法返回值的说明

         4.5 @ApiModel和 @ApiModelProperty

5. 把Swagger2的API接口导入Postman

        1. 访问http://localhost:8080/swagger-ui.html 文档的首页，复制下面这个地址

        2. 打开postman-->import-->Link

        3. 导入成功

6. 问题

        6.1 希望Swagger在生产环境中使用，在发布的时候不使用

        6.2 配置API文档的分组 = >创建多个Docket实例即可；

7. swagger3

        7.1 导入下面这个依赖 把swagger2导入的两个依赖去除

        7.2 把EnableSwagger2注解 换成EnableOpenApi

---

1.为什么使用Swagger2

        在团队开发中，一个好的 API 文档不但可以减少大量的沟通成本，还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节，并在程序员之间代代相传。

这种做法存在以下几个问题：

• API 接口众多，细节复杂，需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等，想要高质量的完成这份文档需要耗费大量的精力；
• 难以维护。随着需求的变更和项目的优化、推进，接口的细节在不断地演变，接口描述文档也需要同步修订，可是文档和代码处于两个不同的媒介，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况

        Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

2.Swagger2 的优点

1. 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本
2. 支持在线接口测试，不依赖第三方工具
3. 代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
4. 跨语言性，支持 40 多种语言。
5. Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
6. 还可以将文档规范导入相关的工具（例如 Postman、SoapUI）, 这些工具将会为我们自动地创建自动化测试

3.快速上手 SpringBoot 集成 Swagger2

        3.1 导入依赖

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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

        3.2 编写配置文件

@Configuration
@EnableSwagger2 //开启Swagger2,这是3.0.0以下版本的注解
public class Swagger2Configuration {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //RequestHandlerSelectors.any()   为任何接口生成API文档
                    //RequestHandlerSelectors.none()  不生成任何接口文档
                    //RequestHandlerSelectors.basePackage("com.neutech.swagger2study")  只为这个包下生成接口文档
                    //RequestHandlerSelectors.withClassAnnotation(Api.class)  为有@Api注解的Controller生成API文档
                    //RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class) 为有@ApiOperation注解的方法生成API文档
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    //PathSelectors.ant("/api/**") 过滤路径 只扫描/api/**的接口 生成接口文档
                    .paths(PathSelectors.ant("/api/**"))
                    .build()
                    ;
    }
    //swagger信息
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("liang","https://zhuanlan.zhihu.com/p/98075551","11794@qq.com");
        return new ApiInfo("Swagger中文文档",
                "描述",
                "v1.0",
                "http://localhost:8080/swagger-ui.html",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

        3.3 控制层

@RestController
@Api(tags = "用户控制层")
@RequestMapping("/api")
public class UserController {

    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public String hello(String name){
        return name;
    }
    @ApiOperation(value="获取用户列表", notes="")
    @RequestMapping(value={"/listUser"}, method= RequestMethod.GET)
    public List<User> getUserList() {
        List list = new ArrayList();
        list.add(new User(1,"zhangsan"));
        return list;
    }
}

        3.4 测试运行 http://localhost:8080/swagger-ui.html        

4. Swagger2注解详解

         4.1 @Api ：请求类的说明

@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
    tags="说明该类的作用"
    value="该参数没什么意义，所以不需要配置"

举例：

@Api(tags = "账户相关模块")
@RestController
@RequestMapping("/api")
public class UserController{
    //TODO
}

        4.2 @ApiOperation：方法的说明

@ApiOperation："用在请求的方法上，说明方法的作用"
    value="说明方法的作用"
    notes="方法的备注说明"

举例：

@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@PostMapping("/changepass")
public AjaxResult changePassword(String username,String password) {
    //TODO
}
@ApiOperation(value="获取用户列表", notes="")
@RequestMapping(value={"/listUser"}, method= RequestMethod.GET)
public List<User> getUserList() {}

         4.3 @ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：对单个参数的说明      
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（请求体）-->  @RequestBody User user
            · form（普通表单提交）     
        dataType：参数类型，默认String，其它值dataType="int"       
        defaultValue：参数的默认值

 举例：

@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
        @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
        @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
        @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
                        @RequestParam Integer age){
    //TODO
    return AjaxResult.OK();
}

单个参数举例：

@ApiOperation("根据部门Id删除")
@ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
    //TODO
}

        4.4 @ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses：方法返回对象的说明
    @ApiResponse：每个参数的说明
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

 举例：

@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径找不到")
})
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
        @RequestBody @Valid PasswordModel passwordModel) {
    //TODO
}

         4.5 @ApiModel和 @ApiModelProperty

@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
    （这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）
@ApiModelProperty：用在JavaBean的属性上面，说明属性的含义  

举例：

@ApiModel("用户实体类") //给生成的文档加注释
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

5. 把Swagger2的API接口导入Postman

        1. 访问http://localhost:8080/swagger-ui.html 文档的首页，复制下面这个地址

        

 

        2. 打开postman-->import-->Link

        3. 导入成功

6. 问题

        6.1 希望Swagger在生产环境中使用，在发布的时候不使用

        思路：判断是不是生产环境（flag=false），再注入enable（flag）；

@Bean
public Docket docket(Environment environment){

    Profiles profiles = Profiles.of("dev");

    //获取项目的环境 environment.acceptsProfiles 判断是否处在自己设定的环境当中(dev环境中)
    boolean flag = environment.acceptsProfiles(profiles);
    return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                //RequestHandlerSelectors.any()   为任何接口生成API文档
                //RequestHandlerSelectors.none()  不生成任何接口文档
                //RequestHandlerSelectors.basePackage("com.neutech.swagger2study")  只为这个包下生成接口文档
                //RequestHandlerSelectors.withClassAnnotation(Api.class)  为有@Api注解的Controller生成API文档
                //RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class) 为有@ApiOperation注解的方法生成API文档
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .build()
                ;
}

        6.2 配置API文档的分组 = >创建多个Docket实例即可；

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket docket1(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docket2(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

    @Bean
    public Docket docket3(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }
    @Bean
    public Docket docket(Environment environment){

        Profiles profiles = Profiles.of("dev");

        //获取项目的环境 environment.acceptsProfiles 判断是否处在自己设定的环境当中(dev环境中)
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(flag)
                    .groupName("liang")
                    .select()
                    //RequestHandlerSelectors.any()   为任何接口生成API文档
                    //RequestHandlerSelectors.none()  不生成任何接口文档
                    //RequestHandlerSelectors.basePackage("com.neutech.swagger2study")  只为这个包下生成接口文档
                    //RequestHandlerSelectors.withClassAnnotation(Api.class)  为有@Api注解的Controller生成API文档
                    //RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class) 为有@ApiOperation注解的方法生成API文档
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    //PathSelectors.ant("/api/**") 过滤路径 只扫描/api/**的接口 生成接口文档
                    .paths(PathSelectors.ant("/api/**"))
                    .build()
                    ;
    }

    private ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("liang","https://zhuanlan.zhihu.com/p/98075551","11794@qq.com");
        return new ApiInfo("Swagger中文文档",
                "描述",
                "v1.0",
                "http://localhost:8080/swagger-ui.html",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

界面展示分组信息

7. swagger3

        7.1 导入下面这个依赖 把swagger2导入的两个依赖去除

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

        7.2 把EnableSwagger2注解 换成EnableOpenApi

@Configuration
//@EnableSwagger2
@EnableOpenApi
public class Swagger2Configuration {}

部分转载：https://www.jianshu.com/p/c79f6a14f6c9

还有狂神说swegger视频