# boot-swagger

**Repository Path**: louie-sun/boot-swagger

## Basic Information

- **Project Name**: boot-swagger
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2020-01-30
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpringBoot 使用 Swagger 插件生成API

## 一、swagger简介
引用官方说明：
> Swagger open source and pro tools have helped millions of API developers, teams, and organizations deliver great APIs.

## 二、SpringBoot项目引入swagger插件
引入插件依赖，以Gradle为例：
```
  compile "io.springfox:springfox-swagger2:2.9.2"
  compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
```

springfox-swagger为针对spring的swagger插件，swagger-ui为界面工具。

## 三、swagger插件常用注解(annotation)说明

### 1. 接口 class 注解
＠Api：接口类说明
> 参数说明：
> value：dtring，接口描述
> tags：数组，接口标签

### 2. 接口 method 注解
@ApiOperation：接口方法说明
> 参数说明：
> value：string,接口名
> notes：string，接口描述
> httpMethod： string,　接口类型，GET/POST/PATH/PUT/DELETE等
> response：Class,返回参数类型
> responseContainer：string, 返回容器，如list

@ApiImplicitParam:接口参数说明
> 参数说明：
> name: string, 参数名称
> value：string,参数标题
> defaultVale: string, 默认值
> required：true/false，是否必须
> paramType：string, 参数类型，head/path/query等
> dataType: string, 参数数据类型，string/int等

@ApiImplicitParams:多个@ApiImplicitParam

### 3. 接口 param 注解

@ApiParam：接口参数说明
> 参数说明：与@ApiImplicitParam基本一致

### 4. ViewModel注解
@ApiModel：模型注解
> 参数说明：
> value: string, 模型名称
> description: string,　模型描述

@ApiModelProperty：模型属性注解
> 参数说明
> name: string, 参数名称
> value: string, 参数标题
> notes: string, 参数描述
> dataType: string, 数据类型
> required: boolean, 是否必须
> example: strign, 示例

### 5. 通用注解

@ApiIgnore：忽略

## 四、插件使用

### 1. 配置插件
新建SwaggerConfig类，使用 `@Configuration` 定义为spring配置类，`@EnableSwagger2` 启用Swagger插件。 

class SwaggerConfig:

```java
@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo () {
        return new ApiInfoBuilder()
                .title("人员服务ＡＰＩ文档")
                .termsOfServiceUrl("https://baidu.com")
                .description("人员相关业务模块ＡＰＩ说明文档")
                .version("v１．０")
                .build();
    }
}

```

### 2. 添加注解

#### 编写一个Restful API接口：

```java
@RestController
@RequestMapping(value = "/user")
public class DemoController {

    @GetMapping(value = "/{userId}")
    public User detail (@PathVariable String userId) {
        return new User(){{
            setUserId(userId);
            setName("jack");
            setAge(18);
        }};
    }

    @GetMapping(value = "/role")
    public List<User> roleUser (String roleId) {
        return new ArrayList<>();
    }

    @PostMapping
    public ResponseEntity<String> create (User user) {
        return new ResponseEntity<>("user created", HttpStatus.OK);
    }

    @PutMapping
    public ResponseEntity<String> update (User user) {
        return new ResponseEntity<>("user updated", HttpStatus.OK);
    }

    @DeleteMapping(value = "/{userId}")
    public ResponseEntity<String> delete (@PathVariable String userId) {
        return new ResponseEntity<>("user deleted, user's primary key is: " + userId, HttpStatus.OK);
    }
}
```

#### 为 Controller 类添加 Swagger 注解：

```java
    @ApiOperation(value = "获取用户", notes = "获取用户详细信息")
    @ApiImplicitParam(name = "userId", value = "user's primary key", required = true)

    @GetMapping(value = "/{userId}")
    public User detail (@PathVariable String userId) {
        return new User(){{
            setUserId(userId);
            setName("jack");
            setAge(18);
        }};
    }
```

#### 为Model添加Swagger注解：

```java
@ApiModel(value = "user model")

@Data
public class User {
    /**
     * user's primary key
     */
    @ApiModelProperty(value = "用户id")
    private String userId;

    /**
     * user's name
     */
    @ApiModelProperty(value = "用户名")
    private String name;

    /**
     * user's age
     */
    @ApiModelProperty(value = "用户年龄")
    private int age;

    /**
     * user's birthday
     */
    @ApiModelProperty(value = "生日")
    private Date birthday;

    /**
     * user's role
     */
    @ApiModelProperty(value = "角色")
    private String role;

    /**
     * user's department
     */
    @ApiModelProperty(value = "部门")
    private String department;
}
```

### 3. 查看文档
启动Application类，访问 `http://localhost:8080/swagger-ui.html`查看API文档：


### 4. 生产环境禁用

API文档在生产环境不可访问，可通过为SwaggerConfig类添加prifile标签实现：

```java
@Configuration
@EnableSwagger2
@Profile(value = {"test", "dev"})
public class SwaggerConfig {

    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo () {
        return new ApiInfoBuilder()
                .title("user api document")
                .description("the api document for user, department and role")
                .termsOfServiceUrl("https://www.baidu.com")
                .version("v1.0.0")
                .build();
    }

}
```