Springboot集成Swagger操作步驟

本文轉載自查看原文 2018-05-07 21:00 43715 swagger/ 后端技術

特別提示：本人博客部分有參考網絡其他博客，但均是本人親手編寫過並驗證通過。如發現博客有錯誤，請及時提出以免誤導其他人，謝謝！歡迎轉載，但記得標明文章出處： http://www.cnblogs.com/mao2080/

1、問題描述

　　隨着互聯網技術的發展，現在的網站架構基本都由原來的后端渲染，變成了：前端渲染、先后端分離的形態，而且前端技術和后端技術在各自的道路上越走越遠。前端和后端的唯一聯系，變成了API接口；API文檔變成了前后端開發人員聯系的紐帶，變得越來越重要，swagger就是一款讓你更好的書寫API文檔的框架，而且swagger可以完全模擬http請求，入參出參和實際情況差別幾乎為零。

　　沒有API文檔工具之前，大家都是手寫API文檔的（維護起來相當困難），在什么地方書寫的都有，有在confluence上寫的，有在對應的項目目錄下readme.md上寫的，每個公司都有每個公司的玩法，無所謂好壞。但是能稱之為“框架”的，估計也只有swagger了

2、操作步驟

　　2.1配置pom.xml

<parent>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-parent</artifactId>
       <version>1.4.0.RELEASE</version>
   </parent>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
  	<!-- junit -->
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <scope>test</scope>
    </dependency>
    <!-- spring boot -->
    <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- swagger -->
    <dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.5.0</version>
	</dependency>
	<!-- swagger-ui -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.5.0</version>
	</dependency>
  </dependencies>

　　 2.2啟動類

package com.mao.swagger;

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

/**
 * Hello world!
 *
 */
@EnableAutoConfiguration
@SpringBootApplication(scanBasePackages = "com.mao")
public class DemoApp {

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

　　　 2.3配置config

package com.mao.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }
	
}

　2.4配置controller

package com.mao.swagger.controller;

import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
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.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.mao.swagger.beans.ResObject;
import com.mao.swagger.beans.User;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

/**
 * Hello world!
 *
 */
@Api(description = "用戶接口")
@RestController
@RequestMapping("/demoController")
public class DemoController {

    @ApiOperation(value = "新增用戶" ,  notes="新增注冊")
    @RequestMapping(value="/createUser",method=RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE)
    public ResObject createUser(@RequestBody User user){
    	System.out.println("createUser:::"+user.toString());
        return new ResObject(HttpStatus.OK.value(), "新增成功.");
    }

    @ApiOperation(value = "修改用戶" ,  notes="修改用戶")
    @RequestMapping(value="/updateUser",method=RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE)
    public ResObject updateUser(@RequestBody User user){
    	System.out.println("updateUser:::"+user.toString());
    	return new ResObject(HttpStatus.OK.value(), "修改成功.");
    }

    @ApiOperation(value = "刪除用戶" ,  notes="刪除用戶")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "userId", value = "用戶標識", required = true, paramType = "query", dataType = "String")
    })
    @RequestMapping(value="/deleteUser",method=RequestMethod.DELETE)
    public ResObject deleteUser(@RequestParam("userId") String userId){
    	System.out.println("deleteUser:::"+userId);
    	return new ResObject(HttpStatus.OK.value(), "刪除成功.");
    }

    @ApiOperation(value = "查詢用戶" ,  notes="查詢用戶")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "userId", value = "用戶標識", required = true, paramType = "query", dataType = "String")
    })
    @RequestMapping(value="/queryUser",method=RequestMethod.GET)
    public ResObject queryUser(@RequestParam("userId") String userId){
    	System.out.println("queryUser:::"+userId);
    	User user = new User(userId, "張三", "******", "mao2080@sina.com");
        return new ResObject(HttpStatus.OK.value(), user);
    }

}