微服务文档输出

Swagger是一款可以用于设计、构建、文档并且执行API的框架。使用框架，可以轻松的创建一个API文档。使用Swagger有利于前后端分离开发，并且在测试的时候不需要在使用浏览器输入URL的方式访问Controller，可以直接在页面输入参数，然后单击按钮来访问。而且传统的输入URL测试方式对于post请求的传参比较麻烦。

• 如何使用Swagger
• 搭建项目框架

pom.xml文件,该文件完整内容如下

  
  4.0.0
  com.microservice
  firstboot
  war
  0.0.1-SNAPSHOT
  firstboot Maven Webapp
  http://maven.apache.org
  
  
    org.springframework.boot
    spring-boot-starter-parent
    1.4.3.RELEASE
  

  
    UTF-8
    1.8
    2.5.0
  

  
    
      org.springframework.boot
      spring-boot-starter-web
    
    
        io.springfox
        springfox-swagger2
        ${springfox.version}
    
    
        io.springfox
        springfox-swagger-ui
        ${springfox.version}
    
    
        org.projectlombok
        lombok
        1.16.8
    
    
    org.mybatis.generator
    mybatis-generator-core
    1.3.2

  


  
  
    
      
        org.springframework.boot
        spring-boot-maven-plugin
       
          
            org.apache.maven.plugins  
            maven-compiler-plugin  
            3.1  
              
            1.8  
            1.8  
            UTF-8  
              
          
    
  

要使用Swagger，首先要引入两个依赖：springfox-swagger2和springfox-swagger-ui。除了必须的两个依赖外，还引入了lombok的依赖。lombok是一个主要用来消除pojo模板试代码（例如getter、setter等）的框架，当然也可以做一些其他事情。需要注意的是，无论是Eclipse还是IDEA想使用lombok，都要安装lombok插件。

在创建好pom.xml文件之后，开始创建主类，主类Application代码如下：

   package com.microservice.firstboot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2  //启动 Swagger
public class Application {
public static void main(String[] args){
    SpringApplication.run(Application.class, args);
    }
}

在该类中除了@SpringBootApplication注解外，还添加了@EnableSwagger2注解，启动Swagger

为了全面的看到Swagger的各种使用方式，这里创建一个模型类com.microservice.firstboot.model.User 代码如下：

 package com.microservice.firstboot.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Getter;

@ApiModel("用户模型")
@AllArgsConstructor
@Getter
public class User {
@ApiModelProperty("用户ID")
private int id;
@ApiModelProperty("用户姓名")
private String name;
@ApiModelProperty("用户密码")
private String password;

}

在该模型中使用了4个注解，分别如下：

• @Getter:是一个Lombok注解，用来为pojo类生成getter方法。如果不添加该注解，我们需要为pojo类生成getter方法，如果一个模型中属性较多，代码就不够简洁。
• @AllArgsConstructor:是一个Lombok注解，用来为pojo生成全参构造器
• @ApiModel：是一个Swagger注解，用来为pojo类做注释
• @ApiModelProperty:是一个Swagger注解，用来为pojo类中属性做注释

核心代码：

   package com.microservice.firstboot.controller;
import com.microservice.firstboot.model.User;
import com.microservice.firstboot.model.Address;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Api("User 相关api")
@RestController
@RequestMapping("/user")
public class FirstSwaggerController {
@ApiOperation("根据ID获得用户信息")
@ApiImplicitParams({
    @ApiImplicitParam(paramType="query",name="id",dataType="int",required=true,value="用户的id",defaultValue="1")
})
@ApiResponses({
    @ApiResponse(code=400,message="请求参数没填好"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
@RequestMapping(value="/getUserInfo",method=RequestMethod.GET)
public User getUserInfo(@RequestParam("id")int id){
    if(id==1){
        return new User(1,"小红","123456");
    }
    return new User(2,"小刚","123456");
}


@ApiOperation("根据ID获得用户住址")
@ApiImplicitParams({
    @ApiImplicitParam(paramType="query",name="id",dataType="int",required=true,value="用户的id",defaultValue="1")
})
@ApiResponses({
    @ApiResponse(code=400,message="请求参数没填好"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
@RequestMapping(value="/getUserAddress",method=RequestMethod.GET)
public Address getUserAddress(@RequestParam("id")int id){
    if(id==1){
        return Address.builder().province("福建省").city("福州市").country("鼓楼区").build();//new User(1,"小红","123456");
    }
    return Address.builder().province("浙江省").city("杭州市").country("余杭区").build();
    }
}

在该controller中，提供了一个简单的接口：根据id获取User。

• @Api:通常用来为一个controller类做注释
• @ApiOperation:通常用来为接口做注释，说明该接口的职能
• @ApiImplicitParams:用来包含接口的一组参数注解，可以将其简单的理解为参数注解的集合
• @ApiImplicitParam:用在@ApiImplicitParams注解中，说明一个请求参数的各个方面。该注解常用选项如下：

• paramType，参数放置的位置，包含query、header、path、body、及form,最常用的是前4个。需要注意的是，query域中的值需要使用@RequestParam获取，path域中的值需要使用@pathVariable获取，body域中的值需要使用@RequestBody获取，否则可能出错。

• name，参数名

• dataType，参数类型

• required，参数是否必须传

• value ，参数的值

• defaultValue ，参数的默认值

• @ApiResponses：通常用来包含接口的一组响应注解，可以将其简单的理解为响应注解的集合

• @ApiResponse：用在@ApiResponses中，一般用来表达一个错误的响应信息

  • code http中code数字，例如400
  • message 信息，例如请求参数没填好

这些注解就是开发中常用的注解：到此Spring Boot与Swagger的集成就完成了。

测试分析Swagger生成的API文档:
启动项目后，浏览器输入 http://localhost:8080/swagger-ui.html#/
使用Swagger进行接口调用如图

Swagger文档

点个关注呗，我负责写，你负责看。

---

• 邮箱：[email protected]
• 技术讨论群：687856230
• GoodLuck