Swagger(一）项目中的swagger配置

╰半夏微凉° 2022-04-15 02:37 365阅读 0赞

**目录**

一.引入依赖；

二.配置swagger

三.界面展示

四：使用swagger注解

五.例子

六.注意：

七：后期需要，再贴出其他相关配置

### 一.引入依赖； ###

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.9.2</version>
 </dependency>
 <dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.9.2</version>
 </dependency>

### 二.配置swagger ###

@Configuration
    @EnableSwagger2
    public class Swagger2Config {
    
    
        /**
         * 创建swagger对象:
         *
         * @return
         */
        @Bean
        public Docket mapRestApi() {
            return new Docket(DocumentationType.SWAGGER_2).groupName("地图坐标转化APIs")
                    .apiInfo(apiInfo()).select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.microservice.http.controller.server.map"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
    
        /**
         * 设置api信息
         * title:swagger题目
         * description:描述
         * cotact:创建者
         *
         * @return
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("微服务API")
                    .description("springboot框架小服务")
                    .contact(new Contact("yourname",null ,"xxx@qq.com"))
                    .version("1.0")
                    .build();
        }
    
    
    }

groupName:当出现多个服务时候，可以用来进行分组

### 三.界面展示 ###

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70][]

### 四：使用swagger注解 ###

** @API**：用在类上，说明该类的作用。

** @ApiOperation**：注解来给API增加方法说明

**@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam （用于get请求）  
    name–参数ming   
   value–参数说明   
  dataType–数据类型   
  paramType–参数类型   
  example–举例说明**

@ApiImplicitParam：用来注解来给方法入参增加说明，表示单独的请求参数。**（用于get请求）**

** @ApiParam()** 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）   
     name–参数名   
    value–参数说明   
   required–是否必填

example- 用例

defaultValue-默认值

@ApiImplicitParam的参数说明：

<table> 
 <tbody> 
 <tr> 
 <td> paramType：指定参数放在哪个地方 </td> 
 <td> header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）--&gt;请求参数的获取：@PathVariable body：（不常用） form（不常用） </td> 
 </tr> 
 <tr> 
 <td> name：参数名 </td> 
 <td> </td> 
 </tr> 
 <tr> 
 <td> dataType：参数类型 </td> 
 <td> </td> 
 </tr> 
 <tr> 
 <td> required：参数是否必须传 </td> 
 <td> true | false </td> 
 </tr> 
 <tr> 
 <td> value：说明参数的意思 </td> 
 <td> </td> 
 </tr> 
 <tr> 
 <td> defaultValue：参数的默认值 </td> 
 <td> </td> 
 </tr> 
 </tbody> 
</table>

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）**（用于post请求）**

**@**ApiModelProperty：描述一个model的属性

### 五.例子 ###

**   get请求：**

//事例1
    @ApiOperation("查询测试")
      @GetMapping("select")
      //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
      @ApiImplicitParams({
      @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
      @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
      public void select(){
    
      }
    
    //事例2
    @Api(value="用户controller",tags={"用户操作接口"})
    @RestController
    public class UserController {
         @ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")
         @GetMapping("/getUserInfo")
         public User getUserInfo(@ApiParam(name="id",value="用户id",required=true,example="123",defaultValue="123") Long id,@ApiParam(name="username",value="用户名") String username) {
         // userService可忽略，是业务逻辑
          User user = userService.getUserInfo();
    
          return user;
      }
    }

**get请求事例1效果图**：

![è¿éåå¾çæè¿°][SouthEast]

**get请求事例2效果图**

![SouthEast 1][]

**post请求：**

@RestController
 @RequestMapping("/server/{version}/map")
 @Api(description = "地图坐标转化服务_APIs")
 public class MapController extends BaseController {
 
 
 @Autowired
 private MapGround2CenterPoint mapGround2CenterPoint;
 
 
 @ApiOperation(value = "地图四至坐标转化",notes = "xxx@qq.com",httpMethod = "POST",produces = MediaType.APPLICATION_STREAM_JSON_VALUE)
 @PostMapping("/mapGround2CenterPoint")
 public List<MapCenterPoint> mapGround2CenterPoint(HttpServletRequest request, HttpServletResponse response, @RequestBody List<MapCenterPointBo> mapCenterPointBos) {
 return mapGround2CenterPoint.mapCenterPoint(mapCenterPointBos);
 }
 
 
 
 }

**实体类：**

@ApiModel(value = "MapCenterPointBo",description = "坐标中心转化的接收参数")
    public class MapCenterPointBo implements Bo{
    
        private static final long serialVersionUID = -6125397442827573980L;
    
        @ApiModelProperty(value = "唯一标识符",dataType = "string",example = "125687897748488")
        private String uniqueId;
    
    
        @ApiModelProperty(value = "四至坐标集合",dataType = "list",example = "116.42765814663355,39.89735517775165|116.43067618613607,39.8974456201949|116.43092331744405,39.89508341943756|116.43016505353685,39.89502445695984")
        private String points;
    
        public String getPoints() {
            return points;
        }
    
        public void setPoints(String points) {
            this.points = points;
        }
    
        public String getUniqueId() {
            return uniqueId;
        }
    
        public void setUniqueId(String uniqueId) {
            this.uniqueId = uniqueId;
        }
    
        @Override
        public boolean equals(Object o) {
            if (this == o) return true;
            if (!(o instanceof MapCenterPointBo)) return false;
            MapCenterPointBo that = (MapCenterPointBo) o;
            return Objects.equals(uniqueId, that.uniqueId) &&
                    Objects.equals(points, that.points);
        }
    
        @Override
        public int hashCode() {
    
            return Objects.hash(uniqueId, points);
        }
    }

###  ###

### 六.注意： ###

1. paramType会直接影响程序的运行期，如果paramType与方法参数获取使用的注解不一致，会直接影响到参数的接收。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70 1][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70 2][]

2.Conntroller中定义的方法必须在@RequestMapper中显示的指定RequestMethod类型，否则SawggerUi会默认为全类型皆可访问， API列表中会生成多条项目。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70 3][]

如上图：updatePassword()未指定requestMethod，结果生成了7条API信息。所以如果没有特殊需求，建议根据实际情况加上requestMethod

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70 4][]

### 七：后期需要，再贴出其他相关配置 ###

参考：[Swagger使用指南\_xusanyao的博客-CSDN博客][Swagger_xusanyao_-CSDN]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70]: /images/20220415/de00b7bc6b5248059c410f7327846327.png
[SouthEast]: /images/20220415/73e39fa52f9243e78dcf5fddae3fd741.png
[SouthEast 1]: /images/20220415/b50577d22df24cf29d32d43c38b250f4.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70 1]: /images/20220415/a234fc1f34f543c88b935cad93fd29ef.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70 2]: /images/20220415/ee5e5669bcea4e678fe0ed1a9eae56a5.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70 3]: /images/20220415/04dbe6f7f68143ef8a2b6d630b1703e3.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI0NjA3ODM3_size_16_color_FFFFFF_t_70 4]: /images/20220415/2f97dfa22ef34eae9b5669950083b93c.png
[Swagger_xusanyao_-CSDN]: https://blog.csdn.net/sanyaoxu_2/article/details/80555328