来自 计算机编程 2019-12-04 16:28 的文章
当前位置: 澳门威尼斯人平台 > 计算机编程 > 正文

SpringBoot 整合(五)Swagger2

Swagger2在SpringBoot环境下的应用

接口管理工具是面向前端的,也是前端与后台沟通的桥梁

简介

详见 SpringMVC集成Swagger

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

1. 集成Swagger

做了小三年的Android开发,也是解除过很多的接口文档工具:

配置

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

1.1 添加依赖

<!--swagger2 start-->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.6.1</version>

</dependency>

<!--引入swagger-ui包-->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.6.1</version>

</dependency>

 

  • word文档
  • apizza
  • postman
  • rap
  • 代码截图
  • txt
  • 口述
  • 直接发代码文件
  • swagger... ...

Maven 配置

 <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <springfox.version>2.2.2</springfox.version>
    </properties>

 <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--Swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>
  </dependencies>

澳门威尼斯人平台 1

1.2 配置类

package com.inn.demo.config;

 

import org.springframework.beans.factory.annotation.Value;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

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;

 

@Configuration

@EnableSwagger2

public class SwaggerConfiguration extends WebMvcConfigurerAdapter {

//生产关闭swagger

@Value("${swagger.enable}")

private boolean enableSwagger;

 

// /**

// * 访问swagger ui 出现404时可以把注释去掉试试

// * 解决资源系统资源目录与swagger ui资源目录冲突问题

// * 这个地方要重新注入一下资源文件,不然不会注入资源的,也没有注入requestHandlerMappping,相当于xml配置的swagger资源配置

// * <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>

// * <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

// * @param registry

// */

// @Override

// public void addResourceHandlers(ResourceHandlerRegistry registry) {

// registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");

// registry.addResourceHandler("swagger-ui.html")

// .addResourceLocations("classpath:/META-INF/resources/");

// registry.addResourceHandler("/webjars/**")

// .addResourceLocations("classpath:/META-INF/resources/webjars/");

// super.addResourceHandlers(registry);

// }

 

// /**

// * 支持分组 groupName

// */

// @Bean(value = "solrRestApi")

// public Docket createSolrRestApi() {

// return new Docket(DocumentationType.SWAGGER_2)

// .apiInfo(apiInfo()).groupName("Solr Demo模块")

// .enable(enableSwagger)

// .select()

// .apis(RequestHandlerSelectors.basePackage("com.inn.demo.modules.solr.web"))

// .paths(PathSelectors.any())

// .build();

// }

 

@Bean(value = "userRestApi")

public Docket createUserRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

//.groupName("用户管理")

.enable(enableSwagger)

.globalOperationParameters(createCommonParams())//公共参数

.select()

.apis(RequestHandlerSelectors.basePackage("com.inn.demo.modules.user.web"))

.paths(PathSelectors.any())

.build();

}

 

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("Demo APIs")

.description("应用实例")

//.termsOfServiceUrl(";)

//.contact(new Contact("开发者1", "", "xxx@163.com"))

.version("1.0")

.build();

}

/**
 * 创建公共参数
 * @return
 */
private List<Parameter> createCommonParams() {
    //添加head参数start
    List<Parameter> pars = new ArrayList<Parameter>();

    ParameterBuilder tokenPar = new ParameterBuilder();
    tokenPar.name("x-access-token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();

    pars.add(tokenPar.build());

    return pars;
    //添加head参数end
}

}

 

但是觉得还是swagger比较方便,主要是不用再去写一份文档。

Application配置

@MapperScan("com.anotherme17.anothernote.mapper")
@SpringBootApplication
@EnableSwagger2
public class AnothernoteApplication {

    /*Swagger*/
    @Bean
    public Docket swaggerSpringMvcPlugin() {
        ApiInfo apiInfo = new ApiInfo("A...", "=  =", "1.0.0",
                "", "...", null, null);
        Docket docket = new Docket(DocumentationType.SWAGGER_2).select().paths(regex("/v1/*/.*")).build()
                .apiInfo(apiInfo).useDefaultResponseMessages(false);
        return docket;
    }

    public static void main(String[] args) {
        SpringApplication.run(AnothernoteApplication.class, args);
    }
}

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

1.3 注解使用

作用范围

API

使用位置

对象属性

@ApiModelProperty

用在出入参数对象的字段上

协议集描述

@Api

用于controller类上

协议描述

@ApiOperation

用在controller的方法上

Response集

@ApiResponses

用在controller的方法上

Response

@ApiResponse

用在 @ApiResponses里边

非对象参数集

@ApiImplicitParams

用在controller的方法上

非对象参数描述

@ApiImplicitParam

用在@ApiImplicitParams的方法里边

描述返回对象的意义

@ApiModel

用在返回对象类上

ApiImplicitParam的相关属性

属性

取值

作用

paramType

path

query

body

header

form

参数放在哪个地方:必须要有这个属性

header:header中提交:@RequestHeader获取

query :key=value提交:@RequestParam获取

path  :地址中提交:@PathVariable获取

body  :json流提交 :@RequestBody获取(限POST)

form  :表单提交:@RequestParam获取(限POST)

dataType

Long

String

参数的数据类型 只作为标志说明,并没有实际验证

name

 

接收参数名

value

 

接收参数的意义描述

required

 

参数是否必填

 

TRUE

必填

 

FALSE

非必填

defaultValue

 

默认值

ApiImplicitParam 与 ApiParam 的区别

ApiImplicitParam: 

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

 

代码实例:

@RestController

@RequestMapping(value = "/user")

@Api(value = "/user", description = "人员基本信息 ")

public class UserController {

 

static Map<String, User> users = Collections.synchronizedMap(new HashMap<String, User>());

 

@ApiOperation(value = "获取用户列表", notes = "")

@RequestMapping(value = {"/list"}, method = RequestMethod.GET)

public List<User> getUserList() {

List<User> r = new ArrayList<User>(users.values());

return r;

}

 

澳门威尼斯人平台,@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")

@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")

@RequestMapping(value = "add", method = RequestMethod.POST)

public String postUser(@RequestBody User user) {

users.put(user.getId(), user);

return "success";

}

 

@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")

@ApiParam(name = "id", value = "用户ID", required = true)

@RequestMapping(value = "/get/{id}", method = RequestMethod.GET)

public User getUser(@PathVariable(value = "id") String id) {

return users.get(id);

}

 

@ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")

@RequestMapping(value = "/update/{id}", method = RequestMethod.PUT)

public String putUser(@PathVariable @ApiParam(name = "id", value = "用户ID", required = true) String id,

@RequestBody @ApiParam(name = "user", value = "用户详细实体user", required = true) User user) {

User u = users.get(id);

u.setName(user.getName());

u.setAge(user.getAge());

users.put(id, u);

return "success";

}

 

@ApiOperation(value = "更新用户名称和年龄", notes = "更新用户名称和年龄")

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String",paramType = "path"),

@ApiImplicitParam(name = "name", value = "用户名", required = true, dataType = "String",paramType = "query"),

@ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "Integer",paramType = "query"),

@ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User",paramType = "body"),

@ApiImplicitParam(name = "headerName", value = "Header信息", required = true, dataType = "String",paramType = "header")

})

@RequestMapping(value = "/update/info/{id}", method = RequestMethod.POST)

public String updateUserNameAndAge(@PathVariable(value = "id") String id,

@RequestParam(value = "name") String name,

@RequestParam(value = "age") Integer age,

@RequestHeader(value = "headerName") String headerName,

@RequestBody User user) {

User u = users.get(id);

u.setName(name);

u.setAge(age);

users.put(id, u);

return "success";

}

 

@ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")

@ApiParam(name = "id", value = "用户ID", required = true)

@RequestMapping(value = "/delete/{id}", method = RequestMethod.DELETE)

public String deleteUser(@PathVariable String id) {

users.remove(id);

return "success";

}

 

@ApiOperation(value="删除用户-传递数组", notes="删除对象,传递数组")

@RequestMapping(value="/users/deleteByIds", method = RequestMethod.DELETE)

public void deleteUsers(@ApiParam("用户ID数组") @RequestParam Integer[] ids) {

for (int id:ids){

users.remove(id);

}

}

}

User实体类:

 

@JsonInclude(JsonInclude.Include.NON_NULL)

@JsonIgnoreProperties({"handler", "hibernateLazyInitializer"})

@ApiModel(value = "User")

public class User {

@ApiModelProperty(value = "ID")

private String id;

 

@ApiModelProperty(value = "姓名", required = true)

private String name;

 

@ApiModelProperty(value = "年龄")

private Integer age;

 

public String getId() {

return id;

}

 

public void setId(String id) {

this.id = id;

}

 

public String getName() {

return name;

}

 

public void setName(String name) {

this.name = name;

}

 

public Integer getAge() {

return age;

}

 

public void setAge(Integer age) {

this.age = age;

}

}

 

好吧,不说废话了,那我们说下怎么配置吧:

配置完成

访问接口 http://[服务器IP]:[端口号]/[项目名]/swagger-ui.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>

本文由澳门威尼斯人平台发布于计算机编程,转载请注明出处:SpringBoot 整合(五)Swagger2

关键词: