Swagger的使用

Swagger

为什么用？

软件开发过程中，前后端分离时，经常出现一些问题而不能尽快解决，导致开发效率变慢。

解决方案

通过使用Swagger接口规范，只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面。

Springboot集成Swagger

springboot通过Maven集成Swagger，需要Springfox。

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

新建Springboot项目

Swagger->Config

• 通过Springboot中配置Swagger,通过Config进行配置
• 通过 @Configuration 注解，让Spring来加载该类配置
• 通过 @EnableSwagger2 注解来启⽤Swagger2

@Configuration
@EnableSwagger2 
public class SwaggerConfig {
    @Bean
    public Docket docket(Environment environment){
        Profiles dev = Profiles.of("dev"); //获得环境
        boolean b = environment.acceptsProfiles(dev);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) //配置文档信息apiInfo
                .groupName("男哥")  //分组
                .enable(b) //是否启动swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yinan.swagger.controller"))//指定要扫描的包
                //.paths(PathSelectors.ant("")) //过滤路径( @GetMapping(value = "/hello"))
                .build();
    }

    //配置文档信息apiInfo
    private ApiInfo apiInfo() {
        Contact contact = new Contact("男哥","https://blog.csdn.net/xinggongzi","1318@qq.com");
        return new ApiInfoBuilder()
                .title("Spring Boot中使⽤Swagger2构建RESTful APIs")
                .description("Hello Swagger")
                .termsOfServiceUrl("https://blog.csdn.net/xinggongzi")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

Controller

返回值存在实体类就会被swagger扫描到

@RestController
public class HelloController {
    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    //返回值存在实体类就会被swagger扫描到
    @PostMapping(value = "/getuser1")
    public User getUser(){
        return new User("nan","123");
    }

    //返回值存在实体类就会被swagger扫描到
    @ApiOperation("获得用户名")
    @GetMapping(value = "/getUser")
    public String getUser1(String name){
        return name;
    }
}

entities

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("密码")
    private String password;

    public User(String name, String password) {

        this.name = name;
        this.password = password;
    }

    public String getName() {
        return name;
    }

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

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

常见文档注释注解

• @ApiModel(“用户实体类”) //给实体类加注释
• @ApiModelProperty(“用户名”) //给实体类属性加注释
• @ApiOperation(“获得用户名”) //给方法加注释

测试

http://localhost:8080/swagger-ui.html