微服务之Swagger

一：swagger是什么？
1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

方法一：使用第三方依赖（最简单的方法）

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项目的启动类上添加@EnableSwagger2Doc注解，就可以直接使用啦。 
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.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

2、swagger的configuration

需要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。

@Configuration  
@EnableSwagger2  
public class Swagger2 {

    public static final String SWAGGER_SCAN_BASE_PACKAGE = "abc.boot.examples.web";
    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))//api接口包扫描路径
                .paths(PathSelectors.any())//可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Swagger2 接口文档示例")//设置文档的标题
            .description("更多内容请关注：http://www.abc.com")//设置文档的描述->1.Overview
            .version(VERSION)//设置文档的版本信息-> 1.1 Version information
            .contact(new Contact("ABC Boot", "http://www.abc.comt", ""))//设置文档的联系方式->1.2 Contact information
            .termsOfServiceUrl("www.abc.com")//设置文档的License信息->1.3 License information
            .build();
    }
}

三、具体使用

1、在API上做一些声明

@ApiOperation

@ApiOperation(value="获取用户列表", notes="获取所有用户列表",produces = "application/json")  
@RequestMapping(value="/users", method= RequestMethod.GET)
public List<User> getUserList() {  
List<User> r = new ArrayList<User>(users.values());
    return r;
}

@ApiResponses 增加返回结果的描述

@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息",produces = "application/json")
@ApiResponses(value = {@ApiResponse(code = 405,message = "Invalid input",response = Integer.class)}) (1)
@ApiImplicitParam(name = "id",value = "用户ID",dataType = "int",paramType = "path")  (2)
@RequestMapping(value="/users/{id}", method= RequestMethod.GET)
public User getUser(@PathVariable Integer id) {
    return users.get(id);
}

(1) 在默认Response的基础上增加新的Response说明
(2) 使用ApiImplicitParam描述接口参数

 

@ApiImplicitParams

@ApiOperation(value="更新用户名称", notes="更新指定用户的名称")
@RequestMapping(value="/users/{id}", method= RequestMethod.POST)
@ApiImplicitParams({  （1）
        @ApiImplicitParam(name = "id",value = "用户ID",paramType = "path",dataType = "int"),  (2)
        @ApiImplicitParam(name = "userName",value = "用户名称",paramType = "form",dataType = "string")
})
public void updateUserName(@PathVariable Integer id,@RequestParam String userName){
    User u = users.get(id);
    u.setName(userName);
}

(1) 使用ApiImplicitParams描述多个参数
(2) 使用ApiImplicitParam时，需要指定paramType,这样也便于swagger ui 生成参数的输入格式。

paramType 有五个可选值 ： path, query, body, header, form

 

@ApiParam

@ApiOperation(value="创建用户-传递简单对象", notes="传递简单对象",produces = "application/json")
@RequestMapping(value="/users-1", method= RequestMethod.POST)
//可以不加ApiParam注解，需要给参数添加描述时可以使用这个注解，或者使用ApiImplicitParams注解 (1)
public Map postUser(@RequestParam  String userName,@ApiParam("地址") @RequestParam(required = false) String address) { 
    User user = new User();
    user.setId(Math.round(10));
    user.setName(userName);
    user.setAddress(address);
    users.put(user.getId(), user);
    return ImmutableMap.of("user",user);
}

(1) 使用ApiParam描述接口参数

ApiImplicitParam 与 ApiParam 的区别
ApiImplicitParam: This is the only way to define parameters when using Servlets or other non-JAX-RS environments.

• 对Servlets或者非 JAX-RS的环境，只能使用 ApiImplicitParam。
• 在使用上，ApiImplicitParam比ApiParam具有更少的代码侵入性，只要写在方法上就可以了，但是需要提供具体的属性才能配合swagger ui解析使用。
• ApiParam只需要较少的属性，与swagger ui配合更好。

 

传递复杂对象 By ModelAttribute

@ApiOperation(value="创建用户-传递复杂对象", notes="传递复杂对象DTO, url参数拼接",produces = "application/json")
@RequestMapping(value="/users-2", method= RequestMethod.POST)
//传递对象推荐使用ModelAttribute注解
public Map postUser2(@ModelAttribute User user) {  (1)
    users.put(user.getId(),user);
    return ImmutableMap.of("user",user);
}

(1) ModelAttribute 是Spring mvc的注解，这里Swagger可以解析这个注解，获得User的属性描述

 

@ApiModel

@ApiModel(value = "User", description = "用户对象")
public class User {

    @ApiModelProperty(value = "ID")
    private Integer id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "地址")
    private String address;
    @ApiModelProperty(value = "年龄",access = "hidden")
    private int age;
    @ApiModelProperty(value = "性别")
    private int sex;
    .......
}

传递复杂对象 By RequestBody

@ApiOperation(value="创建用户-传递复杂对象", notes="传递复杂对象DTO，json格式传递数据",produces = "application/json")
@RequestMapping(value="/users-3", method= RequestMethod.POST)
//json格式传递对象使用RequestBody注解
public User postUser3(@RequestBody User user) {
    users.put(user.getId(),user);
    return user;
}

PathVariable

@ApiOperation(value="删除用户- PathVariable", notes="根据url的id来指定删除对象")
@RequestMapping(value="/users/{id}", method = RequestMethod.DELETE)
public void deleteUser(@PathVariable Integer id) {  (1)
    users.remove(id);
}

(1) PathVariable是Spring 的注解，对于这种简单的参数，就可以不用写ApiParam来描述接口参数。

数组的描述

@ApiOperation(value="删除用户-传递数组", notes="删除对象，传递数组")
@RequestMapping(value="/users/deleteByIds", method = RequestMethod.DELETE)
public void deleteUser(@ApiParam("用户ID数组") @RequestParam Integer[] ids) {  (1)
    for (int id:ids){
        users.remove(id);
    }
}

(1) 这里用ApiParam为数组参数添加描述

 

 

 

参考文档：

https://blog.csdn.net/weixin_37509652/article/details/80094370 

https://www.cnblogs.com/softidea/p/6251249.html