2小时掌握Swagger

简介

官网：https://swagger.io/

前后端分离开发下，API文档说是最好的交流方式不过分吧

Swagger是一个可以生成，描述，可视化RestFul风格的一个框架

1.第一个Hello Swagger

1.1新建springboot项目

1.2添加依赖

<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>

1.3 编写配置

@Configuration
@EnableSwagger2  //开启swagger
public class SwaggerConfig {
    
}

1.4 Controller 层

@Controller
public class MyController {

    @RequestMapping("/hello")
    @ResponseBody
    public String hello(){
        return "hello Swagger";
    }
}

1.5 测试运行

访问地址：http://localhost:8082/swagger-ui.html

出现这个就成功了

1.6 配置swagger的bean实例

 @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    //配置 apiInfo
    private ApiInfo apiInfo(){

        Contact contact = new Contact("扬州炒饭", "https://blog.csdn.net/qq_35800844", "1292893811@qq.com");
        return new ApiInfo(
                "扬州炒饭的Swagger", //标题
                "少说话 多做事", //描述
                "1.0", //版本
                "https://blog.csdn.net/qq_35800844",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }

2.配置swagger扫描接口

 @Value("${spring.profiles.active}")
    private String profiles;


    @Bean
    public Docket docket(){
        boolean bool;
        if(profiles.equals("dev")){
            bool=false;
        }else{
            bool=true;
        }
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo())
                .enable(bool)  //是否打开swagger flase 不打开
                .select()
                //RequestHandlerSelectors  扫描接口的方式
                //basePackage 扫描的包 com.chen.swaggerstudy.controller
                //any() 全部扫描
                //none() 不扫描
                //withClassAnnotation() 扫描类上注解
                //withMethodAnnotation() 扫描方法上注解
                .apis(RequestHandlerSelectors.basePackage("com.chen.swaggerstudy.controller"))
                //过滤路径
                // ant 过滤路径PathSelectors.ant("/chen/**")
                //.paths(PathSelectors.none())
                .build();
    }

3.Swagger的分组

还是在Docket的bean实例中添加

  apiInfo(apiInfo())
                .enable(bool)  //是否打开swagger flase 不打开
                .groupName("炒饭啊")

添加分组

也就是添加多个bean实例

需要详细的话就配置多个ApiInfo 就好了

@Bean
    public Docket docket1(){
        return  new Docket(DocumentationType.SWAGGER_2).groupName("一组");

    }
    @Bean
    public Docket docket2(){
        return  new Docket(DocumentationType.SWAGGER_2).groupName("六组");

    }

4.Swagger常用注解

• @ApiModel 实体类注解
• @ApiModelProperty 实体类字段注解 注意：这块用private 必须有get方法 swagger-ui才显示
• @ApiOperation 表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
• @Api()
  用于类；表示标识这个类是swagger的资源
  tags–表示说明
  value–也是说明，可以使用tags替代
  但是tags如果有多个值，会生成多个list

model:

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("年龄")
    private int age;

    public User(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public User() {
    }

    public String getName() {
        return name;
    }

    public int getAge() {
        return age;
    }

    public void setName(String name) {
        this.name = name;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

controller:

@RestController
public class MyController {

    @ApiOperation("hello请求")
    @PostMapping("/hello")
    public String hello(){
        return "hello Swagger";
    }
    @ApiOperation("test1请求")
    @GetMapping("/test1")
    public String test1(){
        return "hello Swagger";
    }


    @ApiOperation("name参数请求")
    @PostMapping("/name")
    public String name(@ApiParam("姓名")@RequestParam("name") String name){
        return "我叫"+name;
    }
    @ApiOperation("post参数")
    @PostMapping("/post")
    public User post(@ApiParam("姓名") User user){
        return user;
    }
}

总结：

• 可以在线测试
• 可以给接口，实体类添加注释
• 使用简单
• 掌握它还是要多做测试

代码已同步到gitee：点击跳转