SpringBoot 整合(五)Swagger2

日常我们开发完后端接口,如果是返回restful,写API文档是免不了的,Swagger可以帮我们解决大多数问题(自动生成API文档)。

他会帮我们生成一个html页面,大概就是这个样子。

好了,开始正文,如果你觉得有需要的话,往下看。

1. 添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

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

2. 修改启动项

添加注解

@EnableSwagger2   //开启swagger文档生成

3. 给Controller或者字段添加注释

3.1 给Controller方法添加注释。
    @ApiOperation(value = "条件查询用户")
    @GetMapping("/user")
    @JsonView(User.UserSimpleView.class)
    public List query(UserQueryCondition condition,
                      @PageableDefault(page = 2,size = 7,sort = "username,asc")Pageable pageable){

        System.out.println(ReflectionToStringBuilder.toString(condition, ToStringStyle.DEFAULT_STYLE));
        List<User> users = new ArrayList<>();
        users.add(new User());
        users.add(new User());
        users.add(new User());
        return users;
    }

然后访问http://127.0.0.1:8080/swagger-ui.html

3.2 给方法中的字段添加注释

方法一:

    @RequestMapping("/user/{id:\\d+}")
    @ApiImplicitParam(name = "id",value = "用户id")
    public User getInfo( @PathVariable String  id){
        User user = new User();
        user.setUsername("FantJ");
        return user;
    }

方法二:

    @RequestMapping("/user/{id:\\d+}")
    public User getInfo(@ApiParam("用户id") @PathVariable String  id){
        User user = new User();
        user.setUsername("FantJ");
        return user;
    }

方法一是再方法上面加注解,方法二是再参数位加注解。

3.3 给实体类的属性添加注释
    @ApiModelProperty("用户名")
    private String username;

最后所有注解的总结

  • @Api:修饰整个类,描述Controller的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP响应其中1个描述
  • @ApiResponses:HTTP响应整体描述
  • @ApiIgnore:使用该注解忽略这个API
  • @ApiError :发生错误返回的信息
  • @ApiImplicitParam:一个请求参数
  • @ApiImplicitParams:多个请求参数

生产中遇到的问题集锦

1. url是127.0.0.1,但是服务在云主机上。

那如何来配置这个url呢?我们添加一个配置类

package com.tyut.web.config;

import io.swagger.annotations.Contact;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by Fant.J.
 * 2018/4/30 17:20
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.tyut.web.controller";
    public static final String VERSION = "1.0.0";

    ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger API")
                .description("This is to show api description")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .termsOfServiceUrl("")
                .version(VERSION)
//                .contact(new Contact("","", "844072586@qq.com"))  联系方式
                .build();
    }

    @Bean
    public Docket customImplementation(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .build()
                .host("47.xxx.xxx.96")
                .directModelSubstitute(org.joda.time.LocalDate.class, java.sql.Date.class)
                .directModelSubstitute(org.joda.time.DateTime.class, java.util.Date.class)
                .apiInfo(apiInfo());
    }
}
2. 修改controller描述

在controller上加注解@Api(description = "公告API")

©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页