简介

认识Swagger:Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

使用

导入依赖

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

配置Config

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2);
    }
}

Docket

return new Docket(DocumentationType.SWAGGER_2).
                //定义一些
                apiInfo(new ApiInfo(
                        "Api 文档标题",
                        "文档描述",
                        "aip版本",
                        "TermOfService的URL",
                        //对象，代表所有者的一些信息
                        new Contact(
                                "lin",
                                "http://www.apache.org/licenses/LICENSE-2.0",
                                "http://www.apache.org/licenses/LICENSE-2.0"),
                        "Apache 2.0",
                        "http://www.apache.org/licenses/LICENSE-2.0",
                        new ArrayList<>()))
                //是否启动Swagger，false 关闭
                .enable(b)
                //select~build 是完整的一套
                .select()
                //apis 定义要包含的类
                //RequestHandlerSelectors 配置扫描包的方式
                //any 扫描所有
                //none 不扫描
                //basePackage 扫描某个包
                //withClassAnnotation() 对某个注解下的类进行扫描，如withClassAnnotation(Mapping.class)，扫描所有在类上有@Mapping 的类
                //withMethodAnnotation() 同withClassAnnotation() 范围由类变为了方法
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.Controller"))
                //允许您根据路径映射定义应包含哪个控制器的方法
                .paths(PathSelectors.ant("/demo/*"))
                .build();

多配置情况下根据不同配置开启或关闭swagger

        //设置要显示的swagger环境
        Profiles of = Profiles.of("dev");
        //判断是否处于需要的环境下
        boolean b = environment.acceptsProfiles(of);

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles of = Profiles.of("dev");
        //判断是否处于需要的环境下
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(new ApiInfo(
                        "Api 文档标题",
                        "文档描述",
                        "aip版本",
                        "TermOfService的URL",
                        //对象，代表所有者的一些信息
                        new Contact(
                                "lin",
                                "http://www.apache.org/licenses/LICENSE-2.0",
                                "http://www.apache.org/licenses/LICENSE-2.0"),
                        "Apache 2.0",
                        "http://www.apache.org/licenses/LICENSE-2.0",
                        new ArrayList<>()))
                //是否启动Swagger，false 关闭
                .enable(b)
                .select()
                //apis 定义要包含的类
                //RequestHandlerSelectors 配置扫描包的方式
                //any 扫描所有
                //none 不扫描
                //basePackage 扫描某个包
                //withClassAnnotation() 对某个注解下的类进行扫描，如withClassAnnotation(Mapping.class)，扫描所有在类上有@Mapping 的类
                //withMethodAnnotation() 同withClassAnnotation() 范围由类变为了方法
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.Controller"))
                //允许您根据路径映射定义应包含哪个控制器的方法
                .paths(PathSelectors.ant("/demo/*"))
                .build();
    }
}

分组

.groupName("A") 即可分组

下例分为了A，B，index三组

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("A");}
    @Bean
    public Docket docket3(){return new Docket(DocumentationType.SWAGGER_2).groupName("B");}
    @Bean
    public Docket docket(Environment environment){return new Docket(DocumentationType.SWAGGER_2).groupName("index");}

测试

定义一个User类

@AllArgsConstructor
@NoArgsConstructor
@Data
public class User {
    public String name;
    private String pwd;
}

让swagger扫描到

@Controller
public class HelloC {
    @ResponseBody
    @RequestMapping("/demo/hello")
    public String hello(){
        return "hello";
    }
    //接口中存在实体类,就会被swagger扫描到
    @PostMapping("/demo/user")
    public User user(){
        return new User();
    }
}

文档注释 @ApiModel和@ApiModelProperty 会给文档加上相应的注释

@ApiModel("USer的文档注释")
public class User {
    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("密码")
    private String pwd;

    public String getName() {
        return name;
    }

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

    public String getPwd() {
        return pwd;
    }

    public void setPwd(String pwd) {
        this.pwd = pwd;
    }
}

需要注意的是如果没有给private 属性加上get方法是无法添加注释的

@ApiOperation()和@ApiParam

@Controller
public class HelloC {
    //接口中存在实体类,就会被swagger扫描到
    @PostMapping("/demo/user")
    @ApiOperation("User的描述")
    public User user(@ApiParam("注释了n") String n){
        return new User();
    }
}

测试我们可通过Swagger对一些对象进行测试,但使用Springboot时注意返回对象的方法需要@ResponseBody

Springboot-Swagger

简介

使用

导入依赖

配置Config

Docket

分组

测试