9.springboot整合swagger2生成rest-api

1.swagger2说明

swagger是一个api框架,通过注解controller来说明方法的细节,生成一个api文档,启动工程之后访问swagger2的ui页面可以看到生成的文档

2.建立工程

(1)pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">  <modelVersion>4.0.0</modelVersion>  <groupId>com.tyf</groupId>  <artifactId>swagger2-test</artifactId>  <version>0.0.1-SNAPSHOT</version>  <packaging>jar</packaging>  <name>swagger2-test</name>  <url>http://maven.apache.org</url>  <parent>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-parent</artifactId>        <version>1.5.2.RELEASE</version>        <relativePath/>   </parent>  <properties>    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>  </properties>  <dependencies><dependency>              <groupId>org.springframework.boot</groupId>              <artifactId>spring-boot-starter</artifactId>          </dependency>    <dependency>            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-starter-web</artifactId>    </dependency>    <dependency>            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-starter-test</artifactId>            <scope>test</scope>    </dependency>    <!-- swagger2 --><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><!-- swagger2 -->  </dependencies>      <!-- maven插件 -->    <build>        <plugins>            <plugin>                <groupId>org.springframework.boot</groupId>                <artifactId>spring-boot-maven-plugin</artifactId>            </plugin>        </plugins>    </build>            <repositories>        <repository>            <id>spring-milestones</id>            <name>Spring Milestones</name>            <url>https://repo.spring.io/milestone</url>            <snapshots>                <enabled>false</enabled>            </snapshots>        </repository>    </repositories>  </project>

(2)swagger2配置类

主要是写一些基本信息(就是生成在api页面的一些基本信息)

指定要扫描的包下的controller

注释里提供的注解标注在controller中

package com.tyf.swagger2;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;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;/* *  * @Api：修饰整个类，描述Controller的作用  * @ApiOperation：描述一个类的一个方法，或者说一个接口 * @ApiParam：单个参数描述@ApiModel：用对象来接收参数 * @ApiProperty：用对象接收参数时，描述对象的一个字段 * @ApiResponse：HTTP响应其中1个描述 * @ApiResponses：HTTP响应整体描述 * @ApiIgnore：使用该注解忽略这个API * @ApiError ：发生错误返回的信息 * @ApiParamImplicitL：一个请求参数 * @ApiParamsImplicit 多个请求参数 *  *  */@Configuration//表明是一个配置类@EnableSwagger2//开启swagger2public class Swagger2 {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.tyf.swagger2"))//指定会将这个包下面的类会生成api文档,生成规则按照类里面的注解生成                .paths(PathSelectors.any())                .build();    }            //配置一些基本信息    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("这里是title")                .description("这里是description")                .termsOfServiceUrl("这里是个url")                .version("这里是版本")                .build();    }}

(3)controller

package com.tyf.swagger2;import java.awt.print.Book;import java.util.ArrayList;import java.util.Collections;import java.util.HashMap;import java.util.List;import java.util.Map;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.RequestBody;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import org.springframework.web.bind.annotation.RestController;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;import springfox.documentation.annotations.ApiIgnore;@RestController@RequestMapping("/swagger2")public class modelController { Map<Long, model> books = Collections.synchronizedMap(new HashMap<Long, model>());    @ApiOperation(value="说明方法/接口", notes="说明方法/接口其他信息")    @RequestMapping(value={""}, method= RequestMethod.GET)    public List<model> getBook() {        List<model> list = new ArrayList<model>(books.values());        return list;    }    @ApiOperation(value="说明方法/接口", notes="说明方法/接口其他信息")    @ApiImplicitParams({ //下面是多个请求参数分别对应url的参数            @ApiImplicitParam(name = "name1", value = "book属性", required = true, dataType = "String",paramType = "path"),            @ApiImplicitParam(name = "book", value = "book实体", required = true, dataType = "model")    })    //接收一个id参数,从map中更新这个实体    @RequestMapping(value="/update/{id}", method= RequestMethod.PUT)    public String putUser(@PathVariable Long id, @RequestBody Book book) {    //模拟数据库更新操作        model book1 = books.get(id);        book1.setName1("new_name1");        book1.setName2("new_name2");        book1.setName3("new_name3");        books.put(id, book1);        return "success";    }    @ApiIgnore//使用该注解忽略这个API    @RequestMapping(value = "/ignore", method = RequestMethod.GET)    public String  jsonTest() {        return "这个rest请求不生成api";    }    }

(4)app

package com.tyf.swagger2;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplicationpublic class App {    public static void main( String[] args )    {        SpringApplication.run(App.class, args);    }    }

3.访问swagger2的ui查看api

访问

http://localhost:8080/swagger-ui.html