Springboot集成Swagger

Springboot集成Swagger

什么使用?

前后端分离后,维护接口文档基本上是必不可少的工作.
我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:

  • 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
  • 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。

下面我们采用Springboot集成Swagger。

一、增加pomjar包

       <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
     <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>23.0</version>
        </dependency>

二、Swagger2配置


@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.didispace.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多过去的,未来的相关文章请关注:https://www.fengpt.cn/")
                .termsOfServiceUrl("https://www.fengpt.cn/")
                .contact("fengpt")
                .version("1.0")
                .build();
    }

}

三、接下来就是创建接口了

Swagger2相关的注解其实并不多,而且很容易懂,下面我来分别向小伙伴们举例说明:
SysUserController :

@RestController
@RequestMapping("/sys-user")
@Api(tags = "用户Api")
public class SysUserController {

    @Autowired
   private SysUserService sysUserService;
 
    /**
     * 得到用户列表
     * @return
     */
    @PostMapping("/list")
    @ApiOperation("得到用户列表")
    public PageInfo<SysUserDTO> getSysUserList(@RequestBody FindUserListParam findUserListParam){
        SysUserDTO sysUserDTO=new SysUserDTO();
        BeanUtils.copyProperties(findUserListParam, sysUserDTO);
        return sysUserService.getSysUserList(sysUserDTO,findUserListParam.getPageNum(),findUserListParam.getPageSize());
    }
}

@Data
@ApiModel(value = "SysUserDTO", description = "用户")
public class SysUserDTO implements Serializable {

    private  Long id;
    @ApiModelProperty("部门ID")
    private  Long deptId;
    @ApiModelProperty("登录账号")
    private  String loginName;
    @ApiModelProperty("用户昵称")
    private  String userName ;
    @ApiModelProperty("用户类型(0系统用户 1注册用户)")
    private  Integer userType ;
    @ApiModelProperty("用户邮箱")
    private  String   email ;
    @ApiModelProperty("手机号码")
    private  String   phonenumber ;
    @ApiModelProperty("用户性别(0男 1女 2未知)")
    private  Integer  sex ;
    @ApiModelProperty("头像路径")
}

当然可以编写很多接口
image.png

image.png

四、Swagger常用属性说明:

image.png

Swagger更多学习资料:https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html

Copyright: 采用 知识共享署名4.0 国际许可协议进行许可

Links: https://www.fengpt.cn/archives/springboot集成swagger