使用Swagger在SpringBoot项目中管理API文档（使用Oauth2）

1 、修改pom.xml引入swagger
      <!-- Swagger begin -->
        <dependency>

            <groupId>io.springfox</groupId>

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

            <version>2.5.0</version>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>2.5.0</version>

        </dependency>

        <!-- Swagger end -->

2、SwaggerConfig.java
import static com.google.common.collect.Lists.newArrayList;

import static springfox.documentation.builders.PathSelectors.ant;

import java.util.List;

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

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.context.request.async.DeferredResult;

import springfox.documentation.builders.OAuthBuilder;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.ApiKey;

import springfox.documentation.service.AuthorizationCodeGrant;

import springfox.documentation.service.AuthorizationScope;

import springfox.documentation.service.Contact;

import springfox.documentation.service.GrantType;

import springfox.documentation.service.SecurityReference;

import springfox.documentation.service.SecurityScheme;

import springfox.documentation.service.TokenEndpoint;

import springfox.documentation.service.TokenRequestEndpoint;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spi.service.contexts.SecurityContext;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger.web.ApiKeyVehicle;

import springfox.documentation.swagger.web.SecurityConfiguration;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**

 * SwaggerConfig

 */

@Configuration

@EnableSwagger2

public class SwaggerConfig {
@Value("${security.userOauth.clientId}")
private String authClientId;

@Value("${security.userOauth.clientSecret}")
private String authClientSecret;

@Value("${security.userOauth.type}")
private String type;

@Value("${security.userOauth.authorizationUrl}")
private String authorizationUrl;

@Value("${security.userOauth.tokenUrl}")
private String tokenUrl;

@Value("${security.userOauth.tokenName}")
private String tokenName;

@Value("${security.userOauth.scope.code}")
private String scopeCode;

@Value("${security.userOauth.scope.desc}")
private String scopeDesc;

@Value("${app.key}")
private String appKey;

@Value("${app.name}")
private String appName;

@Value("${app.desc}")
private String appDesc;

@Value("${app.version}")
private String appVersion;

@Value("${app.termsOfServiceUrl}")
private String termsOfServiceUrl;

@Value("${app.contact.name}")
private String contactName;

@Value("${app.contact.url}")
private String contactUrl;

@Value("${app.contact.email}")
private String contactEmail;

@Value("${app.license}")
private String license;

@Value("${app.licenseUrl}")
private String licenseUrl;

/**
* Api分组，可以定义多个组
*/
@Bean
public Docket jackApi() {
return new Docket(DocumentationType.SWAGGER_2).groupName("jack")
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(true)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("net.jack.lt"))
.build()
.securitySchemes(newArrayList(oauth()))

4000
.securityContexts(newArrayList(securityContext()))
.apiInfo(jyxApiInfo());
}

private ApiInfo jyxApiInfo() {
ApiInfo apiInfo = new ApiInfo(appName, appDesc, appVersion, termsOfServiceUrl, 
new Contact(contactName, contactUrl, contactEmail),
license, licenseUrl);

return apiInfo;
}

@Bean
SecurityScheme apiKey() {
       return new ApiKey(appName, appKey, "header");
}

@Bean
SecurityContext securityContext() {
AuthorizationScope[] scopes = new AuthorizationScope[]{new AuthorizationScope(scopeCode, scopeDesc)};

SecurityReference securityReference = SecurityReference
.builder()
.reference(type)
.scopes(scopes)
.build();

return SecurityContext
.builder()
.securityReferences(newArrayList(securityReference))
.forPaths(ant("/api/**"))
.build();
}

@Bean
SecurityScheme oauth() {
return new OAuthBuilder()
.name(type)
.grantTypes(grantTypes())
.scopes(scopes())
.build();
}

List<AuthorizationScope> scopes() {
return newArrayList(new AuthorizationScope(scopeCode, scopeDesc));
}

List<GrantType> grantTypes() {
List<GrantType> grants = newArrayList(new AuthorizationCodeGrant(
new TokenRequestEndpoint(authorizationUrl, authClientId, authClientSecret),
new TokenEndpoint(tokenUrl, tokenName)));
return grants;
}

@Bean
public SecurityConfiguration securityInfo() {
return new SecurityConfiguration(authClientId, authClientSecret, scopeCode, 
appKey, appKey, ApiKeyVehicle.HEADER, "", ",");
}

}


3、在RESTful接口上添加注解@ApiOperation @ApiParam
     /**
 * 药品产品列表获取接口
 * pageNo 第几页
 * rows 每页条数
 * @return
 */
@RequestMapping(value = "/products", method = RequestMethod.GET)
@ApiOperation(value = "药品产品列表获取接口", notes = "可指定页码及每页条数")
@ResponseBody
public DrugProducts getDrugProductList(
@ApiParam(value="第几页") @RequestParam(required=false) Integer pageNo, 
@ApiParam(value="每页条数") @RequestParam(required=false) Integer rows) {
     }
或者
     @RequestMapping(value = "/hello", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value="问好", notes="向你问好")
@ApiImplicitParams({

        @ApiImplicitParam(name = "page", value = "第几页", required = false,

                dataType = "int", paramType = "query", defaultValue = "0"),

        @ApiImplicitParam(name = "count", value = "每页行数", required = false,

                dataType = "int", paramType = "query", defaultValue = "30"),

        @ApiImplicitParam(name = "name", value = "姓名", required = false,

                dataType = "string", paramType = "query", defaultValue = "")
})
public CommonParam hello(HttpServletRequest request) {

CommonParam commonParam = new CommonParam();
commonParam.setId(1);
commonParam.setName(request.getParameter("name"));
return commonParam;
}

4、在application.properties或application.yml中增加配置项
security.userOauth.clientId=swagger-ui

security.userOauth.clientSecret=Sa0rk3kgx

security.userOauth.type=oauth2

security.userOauth.authorizationUrl=http://dev.jyx365.top/sso/login

security.userOauth.tokenUrl=http://dev.jyx365.top/oauth/access_token

security.userOauth.tokenName=access_token

security.userOauth.scope.code=userinfo

security.userOauth.scope.desc=用户信息

app.key=learning

app.name=每日一学

app.desc=每日一学RESTful

app.version=0.1

app.termsOfServiceUrl=http://blog.csdn.net/jacktonny1

app.contact.name=闫不由衷

app.contact.url=http://blog.csdn.net/jacktonny1

app.contact.email=hulala208@126.com

app.license=The Apache License, Version 2.0

app.licenseUrl=http://www.apache.org/licenses/LICENSE-2.0.html

或 application.yml

security:

  userOauth:

    clientId: swagger-ui

    clientSecret: Sa0rk3kgx

    type: oauth2

    authorizationUrl: http://dev.jyx365.top/sso/login

    tokenUrl: http://dev.jyx365.top/oauth/access_token

    tokenName: access_token

    scope:

      code: userinfo

      desc: 用户信息

app:

  key: learning

  name: 每日一学

  desc: 每日一学RESTful

  version: 0.1

  termsOfServiceUrl: http://blog.csdn.net/jacktonny1

  contact:

    name: 闫不由衷

    url: http://blog.csdn.net/jacktonny1

    email: hulala208@126.com

  license: The Apache License, Version 2.0

  licenseUrl: http://www.apache.org/licenses/LICENSE-2.0.html

5、http://localhost:端口号/swagger-ui.html