Api接口文档生成工具:Swagger详解(SpringBoot+Swagger集成)
2020-02-05 暂无标签

Swagger-API文档接口引擎

swagger.png

Swagger是什么

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

在项目开发中,根据业务代码自动生成API文档,给前端提供在线测试,自动显示JSON格式,方便了后端与前端的沟通与调试成本。

Swagger有一个缺点就是侵入性模式,必须配置在具体的代码里。

Swagger使用(SpringBoot+Swagger集成)

新建Maven项目

第一种方式:使用第三方依赖

1.在pom.xml文件中添加第三方swagger依赖

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.0.RELEASE</version>
</dependency>

2、在Spring Boot项目的启动类上添加@EnableSwagger2,启动Swagger 
3、https://github.com/SpringForAll/spring-boot-starter-swagger,GitHub上这个swagger依赖实现的项目,里面有详细的讲解。

第二种方式:使用官方依赖

1.在pom.xml文件中添加swagger相关依赖

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
</dependency>
<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
</dependency>
<dependency>
        <groupId>org.codehaus.jackson</groupId>
        <artifactId>jackson-core-asl</artifactId>
        <version>1.9.13</version>
</dependency>

 第一个是API获取的包

第二是官方给出的一个ui界面,这个界面可以自定义,默认是官方的

第三个是测试数据以JSON格式返回的依赖包

2.配置Swagger 

新建Swagger配置类,需要特别注意的是Swagger scan base package,这是扫描注解的配置,即你的API接口位置,对前端提供服务接口的位置。

package com.example.demo.config;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API接口文档")
                .description("用户信息管理")
                .version("1.0.0")
                .build();
    }
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //这里写的是API接口所在的包位置
 
                .paths(PathSelectors.any())
                .build();
    }
}

3.简单写个Dao和User实体类

package com.example.demo.dao;
 
import com.example.demo.entity.User;
public interface UserDao {
    User findById(Integer id);
    User findByName(String name);
 
}
 
 
 
public class User {
    int id;//用户ID
    String name;//姓名
 
    public void setId(int id){
        
        this.id=id;
    }
    public int getId(){
        
        return id;
    }
    public void setName(String name){
        this.name=name;
    }
    public String getName(){
        
        return name;
    }

4.撰写Controller(UserController)

@RestController
@RequestMapping("/user")
@Api(value = "用户信息管理")
public class UserController {
UserDao userDao;
        
    @RequestMapping(method = RequestMethod.POST,value = "/userById")
    @ApiOperation(value = "获取用户信息", notes = "通过用户ID获取用户信息")
    public Object findById(@ApiParam(value = "用户ID",required = true) int id){
        return userDao.findById(id);
    }
 
    @RequestMapping(method = RequestMethod.POST,value = "/userByName")
    @ApiOperation(value = "获取用户信息", notes = "通过用户姓名获取用户信息")
    public Object findByName(@ApiParam(value = "用户姓名",required = true) String  name){
    return userDao.findByName(name); 
    }
 
}

5.设定访问API文档的路由

在配置文件中,application.yml中声明:

springfox.documentation.swagger.v2.path: /api-docs

这个path就是json的访问request mapping.可以自定义,防止与自身代码冲突。

API doc的显示路由是:http://localhost:8080/swagger-ui.html

 

Swagger常用注解

1、Api标记

Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式:

@Api(value = "/user", description = "Operations about user") 

2、ApiOperation标记

ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:

@ApiOperation(

          value = "Find purchase order by ID",

          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",

          response = Order,

          tags = {"Pet Store"})


3、ApiParam标记

ApiParam请求属性,使用方式:

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

  1.  ApiResponse

ApiResponse:响应配置,使用方式: 

@ApiResponse(code = 400, message = "Invalid user supplied") 

  1.  ApiResponses

ApiResponses:响应集配置,使用方式: 

@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) 
  1.  ResponseHeader

响应头设置,使用方法 

@ResponseHeader(name="head1",description="response head conf") 

@Api()用于类; 
表示标识这个类是swagger的资源 
@ApiOperation()用于方法; 
表示一个http请求的操作 
@ApiParam()用于方法,参数,字段说明; 
表示对参数的添加元数据(说明或是否必填等) 
@ApiModel()用于类 
表示对类进行说明,用于参数用实体类接收 
@ApiModelProperty()用于方法,字段 
表示对model属性的说明或者数据操作更改 
@ApiIgnore()用于类,方法,方法参数 
表示这个方法或者类被忽略 
 @ApiImplicitParam() 用于方法 
表示单独的请求参数 
 @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
 @Api() 
用于类;表示标识这个类是swagger的资源 
tags–表示说明 
value–也是说明,可以使用tags替代 
但是tags如果有多个值,会生成多个list

@Api(value="用户controller",tags={"用户操作接口"})

@RestController 

public class UserController {

}

@ApiOperation() 用于方法;表示一个http请求的操作 
value用于方法描述 
notes用于提示内容 
tags可以重新分组(视情况而用) 
@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等) 
name–参数名 
value–参数说明 
required–是否必填

@ApiModel()用于类 ;表示对类进行说明,用于参数用实体类接收 
value–表示对象名 
description–描述 
都可省略 
@ApiModelProperty()用于方法,字段; 表示对model属性的说明或者数据操作更改 
value–字段说明 
name–重写属性名字 
dataType–重写属性类型 
required–是否必填 
example–举例说明 
hidden–隐藏

@ApiIgnore()用于类或者方法上,可以不被swagger显示在页面上 
比较简单, 这里不做举例

@ApiImplicitParam() 用于方法 
表示单独的请求参数 
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam 
name–参数ming 
value–参数说明 
dataType–数据类型 
paramType–参数类型 
example–举例说明

--------------------------------->基础篇

Leave a Reply

如果您是第一次在本站留言,需要审核后才会显示内容!